{ "openapi": "3.1.0", "info": { "title": "HumanTaskBridge API", "version": "1.0.0", "description": "Human-operated asynchronous task requests, free private suggestions and optional support. Read live capabilities before submitting: intakeOpen and preview describe actual availability. Business mutations require X-HTB-Client and idempotency headers. The same-origin aggregate page-view collector and dedicated authenticated mail relay use X-HTB-Client without an idempotency key. No endpoint initiates fund transfers; receiving is verified manually. No administrative email, wallet extended key or internal notes are exposed by unauthenticated public endpoints." }, "servers": [ { "url": "https://humantaskbridge.jimmy-bot-auto.workers.dev", "description": "Public HumanTaskBridge service" } ], "tags": [ { "name": "Tasks" }, { "name": "Suggestions" }, { "name": "Support" }, { "name": "Administration" }, { "name": "Analytics" }, { "name": "Mail relay" } ], "paths": { "/api/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Read services, rules, preview state and limits", "description": "", "tags": ["Tasks"], "security": [], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "preview": { "type": "boolean" }, "intakeOpen": { "type": "boolean" }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "rules": { "type": "array", "items": { "type": "string" } }, "payment": { "type": "object", "properties": { "manualConfirmation": { "const": true }, "btcDerivationEnabled": { "const": false }, "activeEvmNetworks": { "type": "array", "items": { "type": "object", "properties": { "network": { "type": "string" }, "chainId": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "asset": { "type": "string" }, "testnet": { "type": "boolean" } } } } } }, "limits": { "type": "object", "properties": { "maxBodyBytes": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "maxMessages": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "credentialDays": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "submissionsPerIpPerHour": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "globalSubmissionsPerHour": { "type": "integer", "minimum": 0, "maximum": 100000000 } } }, "routes": { "type": "object", "properties": { "request": { "type": "string" }, "suggestion": { "type": "string" }, "support": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/support": { "get": { "operationId": "getSupport", "summary": "List active verified voluntary-support methods", "description": "Contributions do not buy tasks or priority. Agent donations require explicit donation authorization and budget. No transfer is initiated. preview and taskPreview both describe task preview mode. liveContributionsEnabled reflects the explicit SUPPORT_ENABLED flag, not the existence of a receiving method. Real support may be enabled while tasks remain in preview, using only active, verified, owner-confirmed support-only methods. Never use a wallet extended public key as a payment address.", "tags": ["Support"], "security": [], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "preview": { "description": "Task preview state; retained for compatibility. It does not by itself prohibit independently enabled real contributions.", "type": "boolean" }, "taskPreview": { "description": "Task preview state, equal to preview. Task acceptance and payment restrictions remain unchanged.", "type": "boolean" }, "liveContributionsEnabled": { "description": "True only when SUPPORT_ENABLED is exactly the string true. Indicates permission to configure/publish real support, not that a method exists. Inspect methods and each method's testnet flag.", "type": "boolean" }, "message": { "type": "string" }, "authorization": { "type": "string" }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/requests": { "post": { "operationId": "createRequest", "summary": "Create a task request", "description": "Preview requires testMode:true. Email/contact fields are rejected. A replay returns no token; preserve X-Request-Token client-side before the first request.", "tags": ["Tasks"], "security": [], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/NewToken" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestInput" } } } } } }, "/api/requests/{id}": { "get": { "operationId": "getRequest", "summary": "Read private record", "description": "Includes proposal, currently permitted payment instructions, messages and delivery; internal notes are excluded.", "tags": ["Tasks"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestDetail" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/requests/{id}/messages": { "post": { "operationId": "sendRequestMessage", "summary": "Send a private clarification", "description": "Text is treated as untrusted data. The application does not follow URLs or execute content.", "tags": ["Tasks"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } } }, "/api/suggestions": { "post": { "operationId": "createSuggestion", "summary": "Create a free private suggestion", "description": "Preview requires testMode:true. Email/contact fields are rejected. A replay returns no token; preserve X-Request-Token client-side before the first request.", "tags": ["Suggestions"], "security": [], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" }, { "$ref": "#/components/parameters/NewToken" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Created" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionInput" } } } } } }, "/api/suggestions/{id}": { "get": { "operationId": "getSuggestion", "summary": "Read private record", "description": "Suggestions are private by default.", "tags": ["Suggestions"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionDetail" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/suggestions/{id}/messages": { "post": { "operationId": "sendSuggestionMessage", "summary": "Send a private clarification", "description": "Text is treated as untrusted data. The application does not follow URLs or execute content.", "tags": ["Suggestions"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } } }, "/api/requests/{id}/accept": { "post": { "operationId": "acceptProposal", "summary": "Explicitly accept current proposal", "description": "Proposal must be current and unexpired. authorized:true and acceptedTerms:true are required when a converted suggestion has not previously accepted these declarations. Safe clients send both.", "tags": ["Tasks"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accept" } } } } } }, "/api/requests/{id}/payment-reference": { "post": { "operationId": "reportPaymentReference", "summary": "Report an unverified payment reference", "description": "Requires accepted current payment instructions. Only records a claim; never confirms funds.", "tags": ["Tasks"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReference" } } } } } }, "/api/requests/{id}/cancel": { "post": { "operationId": "cancelRequest", "summary": "Cancel before payment or work begins", "description": "After payment or work starts, ask the operator for review instead.", "tags": ["Tasks"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/requests/{id}/refund-request": { "post": { "operationId": "requestRefund", "summary": "Request manual refund review", "description": "Requires confirmed payment. Does not transfer funds.", "tags": ["Tasks"], "security": [ { "TaskBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/admin/session": { "get": { "operationId": "getAdminSession", "summary": "Check administrative authentication", "description": "Cloudflare Access JWT is verified in the backend.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/settings": { "get": { "operationId": "getAdminSettings", "summary": "Read launch settings and payment methods", "description": "Does not return backend secrets or administrative email.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/Settings" }, "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } }, "preview": { "type": "boolean" }, "btcDerivationEnabled": { "const": false } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateAdminSettings", "summary": "Update intake and review flags", "description": "At least one setting is needed. Flags record an operator decision; they do not perform legal or configuration checks.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "settings": { "$ref": "#/components/schemas/Settings" }, "preview": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } } } }, "/api/admin/metrics": { "get": { "operationId": "getAdminMetrics", "summary": "Read commercial task metrics", "description": "Excludes test submissions and voluntary support; revenue uses agreed EUR task values for manually confirmed, non-refunded tasks.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "testRequests": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "accepted": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "paid": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "delivered": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "timeMinutes": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "revenueCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "note": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/notifications": { "get": { "operationId": "listNotifications", "summary": "List up to 200 recent notification results", "description": "No arbitrary outbound mail endpoint exists.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "record_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "status": { "enum": [ "pending", "sending", "simulated", "sent", "failed" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "next_attempt_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": ["string", "null"], "format": "date-time" }, "error_code": { "type": ["string", "null"] } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/notifications/retry": { "post": { "operationId": "retryNotification", "summary": "Retry a failed notification within safe deduplication window", "description": "Sent, simulated and actively sending events cannot be retried. Gmail relay deliveries that have started require manual reconciliation and cannot be automatically resent. Resend delivery more than 23 hours after delivery_started_at requires provider reconciliation. Weekly reports older than 35 days cannot be retried. Quota-deferred events that have never reached the provider have no started-delivery window.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": ["id"] } } } } } }, "/api/admin/payment-methods": { "get": { "operationId": "listPaymentMethods", "summary": "Read configured payment methods", "description": "Initial list is empty. Configuring a wallet address does not activate a network.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPaymentMethod", "summary": "Configure and explicitly verify a receiving method", "description": "BTC methods here are support-only. BTC task addresses are exclusive per proposal/request. EVM must match configured owner address and include chainId, decimals, assetType and token contract where applicable. In task preview, a real method may be activated only with SUPPORT_ENABLED=true, usage=support and explicit owner verification; real tasks/both methods remain blocked. Real contributions also require SUPPORT_ENABLED=true when tasks are live.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } } } }, "/api/admin/payment-methods/{id}": { "post": { "operationId": "updatePaymentMethod", "summary": "Configure and explicitly verify a receiving method", "description": "BTC methods here are support-only. BTC task addresses are exclusive per proposal/request. EVM must match configured owner address and include chainId, decimals, assetType and token contract where applicable. In task preview, a real method may be activated only with SUPPORT_ENABLED=true, usage=support and explicit owner verification; real tasks/both methods remain blocked. Real contributions also require SUPPORT_ENABLED=true when tasks are live.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "paymentMethod": { "$ref": "#/components/schemas/PaymentMethod" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethod" } } } } } }, "/api/admin/requests": { "get": { "operationId": "listAdminRequests", "summary": "List up to 200 recent private records", "description": "Ordered by latest update; filtering can be performed in the private UI.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "testMode": { "type": "boolean" }, "taskStatus": { "type": "string" }, "proposalStatus": { "type": "string" }, "paymentStatus": { "type": "string" }, "status": { "type": "string" }, "budgetCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/requests/{id}": { "get": { "operationId": "getAdminRequest", "summary": "Read full administrative record", "description": "Administrative data must never be exposed by public projections.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRequestDetail" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/requests/{id}/messages": { "post": { "operationId": "sendAdminRequestMessage", "summary": "Publish an operator clarification", "description": "The client retrieves this through the private page/API; no email is sent to a visitor.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } } }, "/api/admin/requests/{id}/purge": { "post": { "operationId": "purgeRequestContent", "summary": "Remove closed operational content", "description": "Requires closed request. Removes submitted text, delivery and notes; retains minimum accounting facts and revokes credential.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "const": true } }, "required": ["confirm"] } } } } } }, "/api/admin/suggestions": { "get": { "operationId": "listAdminSuggestions", "summary": "List up to 200 recent private records", "description": "Ordered by latest update; filtering can be performed in the private UI.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "testMode": { "type": "boolean" }, "taskStatus": { "type": "string" }, "proposalStatus": { "type": "string" }, "paymentStatus": { "type": "string" }, "status": { "type": "string" }, "budgetCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/suggestions/{id}": { "get": { "operationId": "getAdminSuggestion", "summary": "Read full administrative record", "description": "Administrative data must never be exposed by public projections.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSuggestionDetail" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/admin/suggestions/{id}/messages": { "post": { "operationId": "sendAdminSuggestionMessage", "summary": "Publish an operator clarification", "description": "The client retrieves this through the private page/API; no email is sent to a visitor.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } } } }, "/api/admin/suggestions/{id}/purge": { "post": { "operationId": "purgeSuggestionContent", "summary": "Remove closed operational content", "description": "Requires archived or declined suggestion; removes submitted text.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "const": true } }, "required": ["confirm"] } } } } } }, "/api/admin/requests/{id}/proposals": { "post": { "operationId": "createProposal", "summary": "Create a new versioned proposal", "description": "Paid proposals require payment instructions. BTC needs network and exclusive address; EVM needs an active verified task methodId. Price zero does not automatically exempt payment. Revised proposals require new client acceptance.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposalInput" } } } } } }, "/api/admin/requests/{id}/decline": { "post": { "operationId": "declineRequest", "summary": "Decline before payment or execution", "description": "Cannot decline a paid or started task.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/admin/requests/{id}/confirm-payment": { "post": { "operationId": "confirmPayment", "summary": "Record manual receiving-wallet verification", "description": "BTC requires outputIndex. EVM requires chainId and asset; tokens also require contractAddress and logIndex, native assets nativeTransferIndex. Transfer identities are unique across task payments. No chain lookup or transfer occurs. A cancelled task with a previously accepted payable proposal can only record receipt with acknowledgeCanceledPayment:true; it remains cancelled and cannot start. Live/test/network configuration is revalidated at use time.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationInput" } } } } } }, "/api/admin/requests/{id}/free-test": { "post": { "operationId": "approveFreeTest", "summary": "Explicitly exempt an accepted zero-price test", "description": "Requires a test request, accepted current zero-price proposal and no payment instructions.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reason" } } } } } }, "/api/admin/requests/{id}/start": { "post": { "operationId": "startTask", "summary": "Start a confirmed or explicitly exempt task", "description": "Requires taskStatus agreed and payment confirmed/exempt.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/admin/requests/{id}/deliver": { "post": { "operationId": "publishDelivery", "summary": "Publish text and optional HTTP(S) links", "description": "Requires started, confirmed/exempt task. Links are not fetched.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 12000 }, "links": { "type": "array", "maxItems": 10, "items": { "type": "string", "maxLength": 2048, "format": "uri" } } }, "required": ["text"] } } } } } }, "/api/admin/requests/{id}/notes": { "post": { "operationId": "addInternalNote", "summary": "Add private note and optional total tracked minutes", "description": "Internal notes are never returned by client detail.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 5000 }, "timeMinutes": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": ["text"] } } } } } }, "/api/admin/requests/{id}/revoke": { "post": { "operationId": "revokeRequestCredential", "summary": "Revoke private client credential", "description": "Current credential stops working; no secret is returned.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/admin/requests/{id}/refund": { "post": { "operationId": "recordRefundReview", "summary": "Record review or an externally executed refund", "description": "Requires confirmed payment. completed also requires reference. No transfer is performed.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": ["reviewing", "approved", "rejected", "completed"] }, "reason": { "type": "string", "maxLength": 2000 }, "reference": { "type": "string", "maxLength": 200 } }, "required": ["status", "reason"] } } } } } }, "/api/admin/suggestions/{id}/status": { "post": { "operationId": "updateSuggestionStatus", "summary": "Review, archive, decline or mark potential service", "description": "A converted suggestion keeps its conversion status.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "reviewing", "potential_service", "archived", "declined" ] } }, "required": ["status"] } } } } } }, "/api/admin/suggestions/{id}/convert": { "post": { "operationId": "convertSuggestion", "summary": "Start a separate task request from a suggestion", "description": "Inherits the suggestion credential and expiry. Creates an unaccepted, unpaid request; no paid engagement occurs without explicit client authorization, terms and proposal acceptance.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "requestId": { "type": "string", "format": "uuid" }, "tokenExpiresAt": { "type": "string", "format": "date-time" }, "tokenInherited": { "const": true }, "replayed": { "type": "boolean" } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "requestId": { "type": "string", "format": "uuid" }, "tokenExpiresAt": { "type": "string", "format": "date-time" }, "tokenInherited": { "const": true }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/admin/contributions": { "get": { "operationId": "listContributions", "summary": "List up to 200 manually verified voluntary contributions", "description": "Private support ledger, separate from task payments and commercial revenue. No donor identity is collected.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [], "responses": { "200": { "description": "Contribution ledger", "content": { "application/json": { "schema": { "type": "object", "properties": { "contributions": { "type": "array", "items": { "$ref": "#/components/schemas/Contribution" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "recordContribution", "summary": "Record a voluntarily received contribution after manual wallet verification", "description": "Requires an active verified support/both method and explicit receiving-wallet verification. Real contributions require SUPPORT_ENABLED=true; while tasks remain in preview, the method must be support-only. Uses the same transfer-identity uniqueness as service payments, so the same transfer cannot count in both ledgers. Does not initiate a donation, accept service terms or make any task paid.", "tags": ["Administration"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/Idempotency" } ], "responses": { "200": { "description": "Idempotent replay", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "contribution": { "$ref": "#/components/schemas/Contribution" }, "replayed": { "type": "boolean" } } } } } }, "201": { "description": "Manually verified contribution recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "contribution": { "$ref": "#/components/schemas/Contribution" }, "replayed": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource or route not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, version, idempotency or preview conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 32768 bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "JSON required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContributionInput" } } } } } }, "/api/analytics/pageview": { "post": { "operationId": "recordPublicNavigation", "summary": "Record a public in-page navigation without cookies", "description": "Used by the website only after an actual public SPA pathname change. Initial HTTP requests are collected separately and must not be repeated here. Sends no query, fragment, referrer, credential, or browser identifier. Same origin and X-HTB-Client: 1 are required; omit cookies. No Idempotency-Key is required. Do Not Track and Global Privacy Control signals suppress collection. Administrative, private, authentication and unknown paths are excluded. The generic response reveals no visitor or collection data. Unknown paths are ignored with the same 204 response; invalid body types or extra fields return 400.", "tags": ["Analytics"], "security": [], "parameters": [ { "name": "X-HTB-Client", "in": "header", "required": true, "schema": { "const": "1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "example": "/support", "description": "Exact public pathname; only /, /services, /request, /suggest, /support, /docs, /terms, /privacy, /refunds and /acceptable-use are eligible. Unknown paths are ignored. Never include query or fragment." } }, "required": ["path"], "additionalProperties": false } } } }, "responses": { "204": { "description": "No content; no collection details returned." }, "400": { "description": "Invalid JSON body, field types, or unexpected fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/mail-relay/claim": { "post": { "operationId": "claimMailRelayNotification", "summary": "Lease at most one private notification for the authorized SMTP relay", "description": "Machine-only endpoint requiring the dedicated MAIL_RELAY_TOKEN bearer credential and EMAIL_MODE=gmail_relay. This is not a task credential or Cloudflare Access session. Send an empty JSON object and X-HTB-Client: 1; query parameters and target overrides are rejected. Origin and fetch-site checks still apply when those headers are present. No Idempotency-Key is required. A successful claim reserves the shared email budget and a five-minute lease; the caller receives the fixed sole-owner sender and recipient, frozen text, ephemeral leaseToken and deterministic Message-ID. notification:null means no deliverable item, including a quota wait. Do not replay an ambiguous claim to recover its payload. Expired SMTP leases or already attempted deliveries require manual review rather than automatic resend. Responses contain private data and must not be logged or exposed to visitors.", "tags": ["Mail relay"], "security": [{ "MailRelayBearer": [] }], "parameters": [{ "$ref": "#/components/parameters/Client" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "maxProperties": 0 } } } }, "responses": { "200": { "description": "A private notification with a five-minute lease, or no available notification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailRelayClaim" } } } }, "400": { "$ref": "#/components/responses/MailRelayInvalid" }, "401": { "$ref": "#/components/responses/MailRelayUnauthorized" }, "403": { "$ref": "#/components/responses/MailRelayForbidden" }, "413": { "$ref": "#/components/responses/MailRelayTooLarge" }, "415": { "$ref": "#/components/responses/MailRelayUnsupportedMedia" }, "503": { "$ref": "#/components/responses/MailRelayUnavailable" } } } }, "/api/mail-relay/complete": { "post": { "operationId": "completeMailRelayNotification", "summary": "Record one SMTP delivery outcome without sending another email", "description": "Uses the same dedicated relay bearer, JSON body and X-HTB-Client header as claim. No query parameters or Idempotency-Key. Supply the notification id and ephemeral leaseToken returned by claim. Completion must reach the Worker within the five-minute lease. Repeating the same completed outcome with the same lease is idempotent and never sends mail; conflicting outcomes, expired leases and unknown ownership return 409. For sent, optional providerId must equal the claim's deterministic messageId; it is not evidence of inbox delivery or reading. For failed, optional errorCode defaults to smtp_delivery_uncertain. Do not send raw SMTP errors, credentials, recipients or message content in this request. SMTP uncertainty requires manual reconciliation, not automatic resend.", "tags": ["Mail relay"], "security": [{ "MailRelayBearer": [] }], "parameters": [{ "$ref": "#/components/parameters/Client" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MailRelayCompletion" } } } }, "responses": { "200": { "description": "Outcome recorded, or identical completion already recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": ["ok"], "additionalProperties": false } } } }, "400": { "$ref": "#/components/responses/MailRelayInvalid" }, "401": { "$ref": "#/components/responses/MailRelayUnauthorized" }, "403": { "$ref": "#/components/responses/MailRelayForbidden" }, "409": { "description": "Lease unavailable or expired, conflicting outcome, or manual review required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "$ref": "#/components/responses/MailRelayTooLarge" }, "415": { "$ref": "#/components/responses/MailRelayUnsupportedMedia" }, "503": { "$ref": "#/components/responses/MailRelayUnavailable" } } } }, "/api/admin/analytics": { "get": { "operationId": "getAdminWeeklyAnalytics", "summary": "Read a private weekly aggregate traffic report and email readiness", "description": "Requires verified administrative authentication. Select the current UTC week (default, still in progress) or previous completed UTC week. Collection coverage can be partial. The delivery object describes configuration and the selected report state; configuration alone is not proof of email delivery. A mock mode sends no real email.", "tags": ["Administration", "Analytics"], "security": [ { "CloudflareAccess": [] } ], "parameters": [ { "name": "week", "in": "query", "required": false, "schema": { "type": "string", "enum": ["current", "previous"], "default": "current" } } ], "responses": { "200": { "description": "Weekly aggregate report and delivery readiness.", "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "$ref": "#/components/schemas/WeeklyTrafficReport" }, "delivery": { "type": "object", "properties": { "configured": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "mock", "resend", "gmail_relay", "unconfigured" ], "description": "Configured transport mode. gmail_relay is drained by the dedicated external SMTP workflow; configuration alone is not proof of delivery." }, "status": { "type": ["string", "null"] }, "schedule": { "type": "string", "example": "Mondays at 09:00 Europe/Lisbon" }, "sentAt": { "type": ["string", "null"], "format": "date-time", "description": "Provider acceptance timestamp when recorded; not proof of inbox delivery or reading." }, "errorCode": { "type": ["string", "null"], "description": "Redacted operational delivery issue code, when present." } }, "required": ["configured", "mode", "status", "schedule"] } }, "required": ["report", "delivery"] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, revoked or expired credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Persistent quota exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configuration incomplete or intake paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "TaskBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "256-bit base64url credential", "description": "Only the hash is stored. Credential expires after 90 days or earlier revocation. Never use query parameters." }, "CloudflareAccess": { "type": "apiKey", "in": "header", "name": "Cf-Access-Jwt-Assertion", "description": "Signed JWT provided by Cloudflare Access; backend verifies issuer, audience, RS256 signature and sole configured administrator. A plain email header is not authentication." }, "MailRelayBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Dedicated canonical base64url secret of at least 32 random bytes", "description": "Private machine credential matching MAIL_RELAY_TOKEN. Accepted only by the two mail-relay endpoints, independently of task credentials and Cloudflare Access. Never include it in query parameters, logs, browser assets or public examples." } }, "responses": { "MailRelayInvalid": { "description": "Invalid JSON object, unknown fields, query parameters or completion values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MailRelayUnauthorized": { "description": "Missing or invalid dedicated relay bearer credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MailRelayForbidden": { "description": "Missing X-HTB-Client: 1 or denied origin/fetch-site.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MailRelayTooLarge": { "description": "JSON request body exceeds 32768 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MailRelayUnsupportedMedia": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "MailRelayUnavailable": { "description": "gmail_relay mode, dedicated token, sole-owner sender/recipient or canonical HTTPS origin is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "Client": { "name": "X-HTB-Client", "in": "header", "required": true, "schema": { "const": "1" }, "description": "Explicit JSON client header; origin checks still apply." }, "Idempotency": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[\\x21-\\x7e]+$" }, "description": "Keep key and JSON body identical for retries. Stored for seven days." }, "NewToken": { "name": "X-Request-Token", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Recommended: 32 cryptographically random bytes encoded base64url, saved before creation and reused on retries." } }, "schemas": { "MailRelayLeaseToken": { "type": "string", "minLength": 43, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$", "description": "Canonical unpadded base64url credential containing at least 32 bytes. Claim currently generates 32 random bytes. Only its hash is retained as lease ownership." }, "MailRelayClaim": { "type": "object", "required": ["notification"], "additionalProperties": false, "properties": { "notification": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "required": [ "id", "leaseToken", "from", "to", "subject", "text", "messageId" ], "properties": { "id": { "type": "string", "format": "uuid" }, "leaseToken": { "$ref": "#/components/schemas/MailRelayLeaseToken" }, "from": { "type": "string", "format": "email", "description": "Private configured owner identity; identical to the sole authorized recipient." }, "to": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "string", "format": "email" } }, "subject": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Fixed notification subject without control characters." }, "text": { "type": "string", "minLength": 1, "maxLength": 65536, "description": "Private frozen plain-text notification or validated weekly aggregates, without customer-supplied task text." }, "messageId": { "type": "string", "description": "Deterministic RFC Message-ID to preserve when sending and acknowledging; SMTP does not guarantee deduplication from this value." } } } ] } } }, "MailRelayCompletion": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["id", "leaseToken", "outcome"], "properties": { "id": { "type": "string", "format": "uuid" }, "leaseToken": { "$ref": "#/components/schemas/MailRelayLeaseToken" }, "outcome": { "const": "sent" }, "providerId": { "type": "string", "description": "Optional; if supplied, must exactly equal the claim's messageId. The same deterministic value is stored when omitted." } } }, { "type": "object", "additionalProperties": false, "required": ["id", "leaseToken", "outcome"], "properties": { "id": { "type": "string", "format": "uuid" }, "leaseToken": { "$ref": "#/components/schemas/MailRelayLeaseToken" }, "outcome": { "const": "failed" }, "errorCode": { "type": "string", "enum": ["smtp_delivery_failed", "smtp_delivery_uncertain"], "default": "smtp_delivery_uncertain" } } } ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"] }, "Ok": { "type": "object", "properties": { "ok": { "const": true }, "id": { "type": "string", "format": "uuid" }, "replayed": { "type": "boolean" }, "alreadyAccepted": { "type": "boolean" } }, "required": ["ok"] }, "RequestInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 180 }, "description": { "type": "string", "maxLength": 10000 }, "desiredOutcome": { "type": "string", "maxLength": 5000 }, "completionCriteria": { "type": "string", "maxLength": 5000 }, "category": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$", "description": "Use a service ID currently returned by GET /api/capabilities. The operator can edit categories." }, "budgetCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "requestedDeadline": { "type": "string", "format": "date-time" }, "clientName": { "type": "string", "maxLength": 120 }, "authorized": { "const": true }, "acceptedTerms": { "const": true }, "testMode": { "type": "boolean" } }, "required": [ "title", "description", "desiredOutcome", "completionCriteria", "category", "budgetCents", "authorized", "acceptedTerms" ] }, "SuggestionInput": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 180 }, "description": { "type": "string", "maxLength": 10000 }, "desiredOutcome": { "type": "string", "maxLength": 5000 }, "benefit": { "type": "string", "maxLength": 5000 }, "purpose": { "type": "string", "maxLength": 5000 }, "materialsRisks": { "type": "string", "maxLength": 5000 }, "kind": { "enum": ["task", "service"] }, "budgetCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "testMode": { "type": "boolean" } }, "required": [ "title", "description", "desiredOutcome", "benefit", "purpose", "kind" ] }, "Created": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Returned once on first creation; never stored as plaintext. Omitted on replay." }, "tokenExpiresAt": { "type": "string", "format": "date-time" }, "privateUrl": { "type": "string", "pattern": "^/track#id=[a-f0-9-]{36}&kind=(request|suggestion)$", "description": "Supported tracking page with the opaque record ID and kind in its fragment. Contains no access credential; enter the separately saved token on that page." }, "tokenUnavailable": { "type": "boolean" }, "replayed": { "type": "boolean" } }, "required": ["id", "tokenExpiresAt", "privateUrl", "tokenUnavailable"] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "author": { "enum": ["client", "operator"] }, "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "MessageInput": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 5000 } }, "required": ["text"] }, "Reason": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 2000 } }, "required": ["reason"] }, "Accept": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 1000 }, "authorized": { "const": true }, "acceptedTerms": { "const": true } }, "required": ["version"] }, "PaymentReference": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 200 } }, "required": ["reference"] }, "Proposal": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 1000 }, "scope": { "type": "string", "maxLength": 8000 }, "deliverable": { "type": "string", "maxLength": 5000 }, "priceCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "deadline": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PaymentInstructions": { "type": "object", "properties": { "type": { "enum": ["btc", "evm"] }, "network": { "type": "string" }, "asset": { "type": "string" }, "address": { "type": "string" }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "expiresAt": { "type": "string", "format": "date-time" }, "requiredConfirmations": { "type": "integer", "minimum": 1, "maximum": 10000 }, "chainId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "contractAddress": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 }, "assetType": { "enum": ["native", "token"] }, "testnet": { "type": "boolean" }, "qrDataUrl": { "type": "string", "description": "Locally generated QR containing the address; network, asset and amount remain explicit adjacent text." } } }, "ProposalInput": { "type": "object", "properties": { "scope": { "type": "string", "maxLength": 8000 }, "deliverable": { "type": "string", "maxLength": 5000 }, "priceCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "deadline": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "payment": { "type": "object", "properties": { "type": { "enum": ["btc", "evm"] }, "network": { "enum": ["bitcoin", "bitcoin-testnet"] }, "address": { "type": "string", "maxLength": 150 }, "methodId": { "type": "string", "format": "uuid" }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "expiresAt": { "type": "string", "format": "date-time" }, "requiredConfirmations": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "amountAtomic", "expiresAt", "requiredConfirmations" ] } }, "required": [ "scope", "deliverable", "priceCents", "deadline", "expiresAt" ] }, "RequestView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "desiredOutcome": { "type": "string" }, "completionCriteria": { "type": "string" }, "category": { "type": "string" }, "budgetCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "requestedDeadline": { "type": "string", "format": "date-time" }, "clientName": { "type": "string" }, "testMode": { "type": "boolean" }, "taskStatus": { "enum": [ "submitted", "agreed", "in_progress", "delivered", "declined", "cancelled" ] }, "proposalStatus": { "enum": ["none", "offered", "accepted", "expired", "cancelled"] }, "paymentStatus": { "enum": [ "unpaid", "pending", "claimed", "confirmed", "exempt", "refund_requested", "refunded" ] }, "acceptedProposalVersion": { "type": ["integer", "null"] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Refund": { "type": "object", "properties": { "status": { "type": "string" }, "reason": { "type": "string" }, "reference": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Delivery": { "type": "object", "properties": { "text": { "type": "string" }, "links": { "type": "array", "items": { "type": "string", "format": "uri" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "RequestDetail": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/RequestView" }, "proposal": { "anyOf": [ { "$ref": "#/components/schemas/Proposal" }, { "type": "null" } ] }, "payment": { "type": "object", "properties": { "status": { "type": "string" }, "instructions": { "anyOf": [ { "$ref": "#/components/schemas/PaymentInstructions" }, { "type": "null" } ] }, "instructionsExpired": { "type": "boolean" }, "references": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "confirmation": { "type": ["object", "null"], "properties": { "txid": { "type": "string" }, "amountAtomic": { "type": "string" }, "verifiedAt": { "type": "string", "format": "date-time" } } }, "freeTestExemption": { "type": "boolean" } }, "description": "Payment instructions and QR are shown to the client only for an accepted current proposal in pending/claimed state while valid and allowed by current configuration." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "delivery": { "anyOf": [ { "$ref": "#/components/schemas/Delivery" }, { "type": "null" } ] }, "refunds": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } } }, "required": [ "request", "proposal", "payment", "messages", "delivery", "refunds" ] }, "SuggestionView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "desiredOutcome": { "type": "string" }, "benefit": { "type": "string" }, "purpose": { "type": "string" }, "materialsRisks": { "type": "string" }, "budgetCents": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "kind": { "enum": ["task", "service"] }, "testMode": { "type": "boolean" }, "status": { "enum": [ "submitted", "reviewing", "potential_service", "archived", "declined", "converted" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "convertedRequestId": { "type": "string", "format": "uuid" } } }, "SuggestionDetail": { "type": "object", "properties": { "suggestion": { "$ref": "#/components/schemas/SuggestionView" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": ["suggestion", "messages"] }, "PaymentMethod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": ["btc", "evm"] }, "name": { "type": "string", "maxLength": 100 }, "network": { "type": "string", "maxLength": 100 }, "asset": { "type": "string", "maxLength": 32 }, "address": { "type": "string", "maxLength": 150 }, "usage": { "enum": ["support", "tasks", "both"] }, "active": { "type": "boolean" }, "verified": { "type": "boolean" }, "verifiedByOwner": { "type": "boolean" }, "testnet": { "type": "boolean" }, "chainId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "assetType": { "enum": ["native", "token"] }, "contractAddress": { "type": "string" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 36 }, "qrDataUrl": { "type": "string" } }, "required": ["type", "name", "network", "asset", "address", "usage"] }, "Settings": { "type": "object", "properties": { "intakePaused": { "type": "boolean" }, "legalReady": { "type": "boolean" }, "launchReady": { "type": "boolean" }, "services": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,39}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "description": "Unique IDs; changing this list changes accepted categories for new requests." } }, "minProperties": 1, "additionalProperties": false }, "Session": { "type": "object", "properties": { "authenticated": { "const": true }, "preview": { "type": "boolean" }, "csrfToken": { "const": "1", "description": "Use X-HTB-Client: 1. This is not an authentication credential." }, "localMock": { "type": "boolean" } } }, "ConfirmationInput": { "type": "object", "properties": { "verifiedInWallet": { "const": true }, "txid": { "type": "string", "pattern": "^(0x)?[a-fA-F0-9]{64}$" }, "recipient": { "type": "string", "maxLength": 150 }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "confirmations": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "verificationNote": { "type": "string", "maxLength": 2000 }, "outputIndex": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "chainId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "asset": { "type": "string" }, "contractAddress": { "type": "string" }, "logIndex": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "nativeTransferIndex": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "acknowledgeLatePayment": { "type": "boolean" }, "acknowledgeCanceledPayment": { "type": "boolean", "description": "Explicit operator acknowledgement when recording received funds for a cancelled task. Keeps the task cancelled and does not authorize execution; enables manual refund review." } }, "required": [ "verifiedInWallet", "txid", "recipient", "amountAtomic", "confirmations", "verificationNote" ] }, "AdminRequestDetail": { "allOf": [ { "$ref": "#/components/schemas/RequestDetail" }, { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } }, "internalNotes": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "timeMinutes": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "tokenExpiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": ["string", "null"], "format": "date-time" }, "paymentConfirmation": { "type": ["object", "null"] }, "sourceSuggestionId": { "type": "string", "format": "uuid" } } } ] }, "AdminSuggestionDetail": { "allOf": [ { "$ref": "#/components/schemas/SuggestionDetail" }, { "type": "object", "properties": { "tokenExpiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": ["string", "null"], "format": "date-time" } } } ] }, "Contribution": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "method": { "$ref": "#/components/schemas/PaymentMethod" }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "testMode": { "type": "boolean" }, "confirmation": { "type": "object" }, "notes": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } }, "ContributionInput": { "type": "object", "properties": { "verifiedInWallet": { "const": true }, "txid": { "type": "string", "pattern": "^(0x)?[a-fA-F0-9]{64}$" }, "recipient": { "type": "string", "maxLength": 150 }, "amountAtomic": { "type": "string", "pattern": "^[1-9][0-9]{0,77}$" }, "confirmations": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "verificationNote": { "type": "string", "maxLength": 2000 }, "outputIndex": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "chainId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "asset": { "type": "string" }, "contractAddress": { "type": "string" }, "logIndex": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "nativeTransferIndex": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "acknowledgeLatePayment": { "type": "boolean" }, "methodId": { "type": "string", "format": "uuid" }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "verifiedInWallet", "txid", "recipient", "amountAtomic", "confirmations", "verificationNote", "methodId" ] }, "WeeklyTrafficReport": { "type": "object", "properties": { "period": { "type": "object", "properties": { "week": { "type": "string", "pattern": "^[0-9]{4}-W[0-9]{2}$" }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time", "description": "Exclusive UTC week boundary." }, "timezone": { "const": "UTC" } }, "required": ["week", "start", "end", "timezone"] }, "generatedAt": { "type": "string", "format": "date-time" }, "coverage": { "type": "object", "properties": { "trackingStartedAt": { "type": ["string", "null"], "format": "date-time" }, "observedThrough": { "type": "string", "format": "date-time" }, "partial": { "type": "boolean", "description": "True for a current week, late collection start, or unknown collection start. Earlier traffic is not reconstructed." } }, "required": ["trackingStartedAt", "observedThrough", "partial"] }, "totals": { "type": "object", "properties": { "pageViews": { "type": "integer", "minimum": 0 }, "httpPageViews": { "type": "integer", "minimum": 0 }, "spaPageViews": { "type": "integer", "minimum": 0 }, "agentResourceViews": { "type": "integer", "minimum": 0 }, "httpEntrances": { "type": "integer", "minimum": 0 }, "estimatedWeeklyVisitors": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "unclassified": { "type": "integer", "minimum": 0 }, "knownBot": { "type": "integer", "minimum": 0 } }, "required": ["total", "unclassified", "knownBot"] }, "estimatedWeeklyAgentVisitors": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "unclassified": { "type": "integer", "minimum": 0 }, "knownBot": { "type": "integer", "minimum": 0 } }, "required": ["total", "unclassified", "knownBot"] } }, "required": [ "pageViews", "httpPageViews", "spaPageViews", "agentResourceViews", "httpEntrances", "estimatedWeeklyVisitors", "estimatedWeeklyAgentVisitors" ] }, "pages": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "enum": [ "/", "/services", "/request", "/suggest", "/support", "/docs", "/terms", "/privacy", "/refunds", "/acceptable-use" ] }, "views": { "type": "integer", "minimum": 0 }, "httpViews": { "type": "integer", "minimum": 0 }, "spaViews": { "type": "integer", "minimum": 0 }, "knownBotViews": { "type": "integer", "minimum": 0 }, "unclassifiedViews": { "type": "integer", "minimum": 0 } }, "required": [ "path", "views", "httpViews", "spaViews", "knownBotViews", "unclassifiedViews" ] } }, "agentResources": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "enum": ["/api/support", "/llms.txt", "/openapi.json"] }, "views": { "type": "integer", "minimum": 0 }, "knownBotViews": { "type": "integer", "minimum": 0 }, "unclassifiedViews": { "type": "integer", "minimum": 0 } }, "required": [ "path", "views", "knownBotViews", "unclassifiedViews" ] } }, "countries": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code, or unknown." }, "views": { "type": "integer", "minimum": 0 }, "pageViews": { "type": "integer", "minimum": 0 }, "agentResourceViews": { "type": "integer", "minimum": 0 } }, "required": [ "country", "views", "pageViews", "agentResourceViews" ] } }, "referrers": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": ["direct", "search", "social", "other"] }, "httpEntrances": { "type": "integer", "minimum": 0 } }, "required": ["source", "httpEntrances"] } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "period", "generatedAt", "coverage", "totals", "pages", "agentResources", "countries", "referrers", "limitations" ], "description": "Aggregate observations, not verified human counts. Known bots are separated from unclassified traffic, which may include undetected automation. Website and agent-resource visitor estimates overlap and must not be summed. Raw IPs, user-agent strings, full referrers, queries and credentials are not returned." } } } }