{ "openapi": "3.1.0", "info": { "title": "K-Work Trust API", "version": "0.1.0", "description": "Remote MCP/API trust gates for AI agents before they write Korean vendor, invoice, payment, CRM, or ecommerce business records." }, "servers": [ { "url": "https://k-work-trust-api.fly.dev", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyAuth": [] } ], "paths": { "/health": { "get": { "summary": "Health check", "security": [], "responses": { "200": { "description": "Service is healthy" } } } }, "/v1/agent/readiness": { "get": { "summary": "Agent deployment readiness", "description": "Public machine-readable deployment readiness for autonomous or invited agent use. Does not expose API keys or secrets.", "security": [], "responses": { "200": { "description": "Deployment readiness summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentReadiness" } } } } } } }, "/v1/auth/whoami": { "get": { "summary": "Inspect the current API key", "description": "Verifies an API key and returns trust level, rate limit, monthly quota usage, and official-source policy without consuming monthly quota.", "responses": { "200": { "description": "Authenticated API key status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWhoami" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tools": { "get": { "summary": "List available tools", "responses": { "200": { "description": "Tool list" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/tools/call": { "post": { "summary": "Call any K-Work Trust tool", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tool" ], "properties": { "tool": { "type": "string", "examples": [ "validate_vendor_onboarding" ] }, "arguments": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Unsupported tool" }, "422": { "description": "Invalid tool input" } } } }, "/v1/vendor-onboarding/validate": { "post": { "summary": "Validate a Korean vendor onboarding record", "description": "Best first endpoint for external agents. Combines business registration, company name, address, phone, and evidence checks into one workflow decision.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Invalid vendor record" } } } }, "/v1/invoice-readiness/validate": { "post": { "summary": "Validate invoice readiness", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" } } } }, "/v1/payment-or-invoice-release/validate": { "post": { "summary": "Validate payment or invoice release", "description": "Use before an agent releases a payment, invoice, settlement, purchase order, or other money-adjacent workflow step. Returns allow/review/block style decisions, amount policy, required fixes, and a human review packet.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/document-cross-check/validate": { "post": { "summary": "Validate document cross-check", "description": "Use before an agent trusts a vendor document bundle, invoice fields, contract metadata, or bank-account fields. Returns match/mismatch decisions, required fixes, and a human review packet.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/vendor-reverification/validate": { "post": { "summary": "Validate vendor reverification", "description": "Use before an agent keeps using an already-onboarded vendor. Returns continued-use, reverify, or stop decisions based on vendor status, verification age, official-source requirement, and high-risk flags.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-action-firewall/validate": { "post": { "summary": "Validate agent action firewall", "description": "Use before an agent posts externally, pushes to GitHub, deploys, changes state, or handles sensitive inputs. Returns allow, approval-required, or blocked decisions with policy checks and a human review packet.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/technical-due-diligence/validate": { "post": { "summary": "Validate technical due diligence", "description": "Use before an agent trusts a repository, API, MCP server, package, SDK, or technical service. Returns limited-use, review, or do-not-use decisions with build, test, secret-scan, dependency, documentation, and agent-contract evidence.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/supply-chain-provenance/validate": { "post": { "summary": "Validate supply-chain provenance", "description": "Use before an agent trusts an artifact, package, repository, SDK, or release. Returns trust-with-constraints, review, or do-not-use decisions based on provenance, signatures, SBOM, pins, dependency risk, and vulnerability evidence.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/secret-flow/validate": { "post": { "summary": "Validate secret flow", "description": "Use before an agent handles credentials or secret-bearing data. Returns decisions based on secret-scan, taint-flow, redaction, secret-manager, prompt, log, and output-sink evidence.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/api-contract-drift/validate": { "post": { "summary": "Validate API contract drift", "description": "Use before an agent integrates or upgrades an API/MCP contract. Returns decisions based on breaking changes, removed paths, schema drift, auth or quota changes, versioning, migration, and client-test evidence.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/policy-invariants/validate": { "post": { "summary": "Validate policy invariants", "description": "Use before an agent relies on policy-as-code or model-check evidence. Returns decisions based on approval, quota, plaintext-secret, first-call, paid-action, audit, rollback, and deny-by-default invariants.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-endpoint-fuzzing/validate": { "post": { "summary": "Validate agent endpoint fuzzing", "description": "Use before exposing an endpoint to autonomous callers. Returns decisions based on fuzz/property test coverage, crashes, auth bypasses, leaks, schema violations, latency, 5xx rate, rate limits, and destructive-payload guards.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-plan/compile": { "post": { "summary": "Compile agent plan", "description": "Compile an agent plan into a bounded transition model with normalized actions, action graph, and safety issues.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-policy-invariants/prove": { "post": { "summary": "Prove agent policy invariants", "description": "Check agent plan invariants and return proved invariants, failed invariants, and bounded counterexamples.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-counterexample/find": { "post": { "summary": "Find agent counterexample", "description": "Find a short unsafe execution trace for an agent plan when supplied invariants fail.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-risk-bound/estimate": { "post": { "summary": "Estimate agent risk bound", "description": "Estimate an upper risk bound for an agent plan using action risks and invariant penalties.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-tail-risk/estimate": { "post": { "summary": "Estimate agent tail risk", "description": "Estimate dependency-adjusted loss distribution, VaR, and CVaR tail risk for an agent plan.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-evidence-quality/score": { "post": { "summary": "Score agent evidence quality", "description": "Score an evidence packet before an agent relies on it, using required-claim coverage, source entropy, freshness decay, confidence, provenance metadata, and contradiction penalties.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-trust-contracts/compose": { "post": { "summary": "Compose agent trust contracts", "description": "Compose multiple service trust contracts into a workflow graph certificate and surface weak services, incompatible dependency edges, and missing first-safe-call boundaries.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/autonomy-budget/optimize": { "post": { "summary": "Optimize autonomy budget", "description": "Choose which agent actions can run autonomously under risk and money budgets, and which need review.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-temporal-safety/model-check": { "post": { "summary": "Model-check agent temporal safety", "description": "Explore dependency-respecting execution orders within explicit bounds and return temporal counterexamples plus a minimal intervention set.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agent-trust-certificate/issue": { "post": { "summary": "Issue agent trust certificate", "description": "Issue an Agent Trust Compiler certificate with plan model, invariant proof, temporal model check, counterexamples, risk bound, and autonomy budget.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/open-world-trust-certificate/issue": { "post": { "summary": "Issue open-world trust certificate", "description": "Issue a bounded open-world trust certificate by composing proof packets, argument provenance, adversarial policy checks, assumptions, known unknowns, and active monitors.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/open-world-proof-carrying-autonomy/authorize": { "post": { "summary": "Authorize open-world proof-carrying autonomy", "description": "Authorize end-to-end open-world proof-carrying autonomy with lifecycle phases, runtime monitors, renewal deadlines, revocation triggers, and audit boundaries.", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/crm-company-record/clean": { "post": { "summary": "Clean a CRM company record", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" } } } }, "/v1/record-risk/score": { "post": { "summary": "Score record risk", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" } } } }, "/v1/evidence-report/generate": { "post": { "summary": "Generate evidence report", "requestBody": { "$ref": "#/components/requestBodies/VendorRecord" }, "responses": { "200": { "$ref": "#/components/responses/ToolResponse" } } } }, "/.well-known/k-work-trust-agent.json": { "get": { "summary": "Canonical K-Work Trust agent discovery manifest", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest" } } } }, "/.well-known/service.json": { "get": { "summary": "Preferred generic service discovery manifest", "security": [], "responses": { "200": { "description": "Machine-readable generic service manifest for agents and directories" } } } }, "/.well-known/agent.json": { "get": { "summary": "Generic agent discovery manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest" } } } }, "/.well-known/agent-trust-contract.json": { "get": { "summary": "Agent Trust Contract Kit discovery manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable Agent Trust Contract Kit manifest" } } } }, "/.well-known/tool.json": { "get": { "summary": "Generic tool/service discovery manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest" } } } }, "/agent.json": { "get": { "summary": "Legacy agent discovery manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest" } } } }, "/service.json": { "get": { "summary": "Root generic service discovery manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest" } } } }, "/v1/agent/discovery": { "get": { "summary": "Agent discovery manifest API alias", "security": [], "responses": { "200": { "description": "Machine-readable agent manifest" } } } }, "/.well-known/agent-directory.json": { "get": { "summary": "External directory listing metadata", "security": [], "responses": { "200": { "description": "Directory-optimized listing metadata for external agent, API, and MCP catalogs", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/directory.json": { "get": { "summary": "External directory listing alias", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agent-directory.json": { "get": { "summary": "Root external directory listing alias", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/directory.json": { "get": { "summary": "Root directory listing metadata", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/directory": { "get": { "summary": "Directory listing API alias", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/mcp.json": { "get": { "summary": "Remote MCP directory manifest", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/mcp.json": { "get": { "summary": "Root Remote MCP directory manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/ai-plugin.json": { "get": { "summary": "AI plugin compatibility manifest", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/ai-plugin.json": { "get": { "summary": "Root AI plugin compatibility manifest alias", "security": [], "responses": { "200": { "description": "Machine-readable public discovery document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/openapi.json": { "get": { "summary": "Well-known OpenAPI alias", "security": [], "responses": { "200": { "description": "OpenAPI specification alias", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/agent-trust-contract.md": { "get": { "summary": "Agent Trust Contract Kit summary", "security": [], "responses": { "200": { "description": "Human-readable discovery contract for AI agents and operators", "content": { "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/directory.md": { "get": { "summary": "External directory submission pack", "security": [], "responses": { "200": { "description": "Human-readable listing pack for external directories and community posts", "content": { "text/markdown": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "summary": "LLM-readable service index", "security": [], "responses": { "200": { "description": "Plain-text service index for LLMs and agents", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/.well-known/llms.txt": { "get": { "summary": "LLM-readable service index", "security": [], "responses": { "200": { "description": "Plain-text service index for LLMs and agents", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/robots.txt": { "get": { "summary": "Crawler discovery hints", "security": [], "responses": { "200": { "description": "Robots and sitemap hints for public discovery endpoints", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/sitemap.xml": { "get": { "summary": "Public discovery sitemap", "security": [], "responses": { "200": { "description": "Sitemap containing public discovery endpoints", "content": { "application/xml": { "schema": { "type": "string" } }, "text/xml": { "schema": { "type": "string" } } } } } } }, "/skill.md": { "get": { "summary": "Agent skill instructions", "security": [], "responses": { "200": { "description": "Markdown instructions for AI agents" } } } }, "/mcp": { "post": { "summary": "Remote MCP Streamable HTTP endpoint", "description": "Accepts single JSON-RPC MCP requests for initialize, tools/list, and tools/call. initialize and tools/list are public for discovery. tools/call uses the same API key, quota, official-source, and abuse-guard policies as protected REST workflow calls.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "JSON-RPC MCP response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/AgentError" }, "429": { "$ref": "#/components/responses/AgentError" } } }, "get": { "summary": "Remote MCP SSE stream status", "description": "Returns 405 because this deployment currently supports JSON-response Streamable HTTP POST only.", "responses": { "405": { "description": "SSE streams are not enabled" } } } }, "/v1/agent/signup/challenge": { "get": { "summary": "Create an agent self-signup proof-of-work challenge", "security": [], "parameters": [ { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "$ref": "#/components/responses/AgentChallenge" }, "404": { "$ref": "#/components/responses/AgentError" }, "422": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/status": { "get": { "summary": "Agent signup status and public policy", "security": [], "responses": { "200": { "description": "Machine-readable public signup status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignupStatus" } } } } } } }, "/v1/agent/runtime/errors": { "get": { "summary": "Agent runtime error and payload-size contract", "description": "Public machine-readable retry, abort, escalation, and max-payload guidance for autonomous agents. Does not expose keys, private records, or production payloads.", "security": [], "responses": { "200": { "description": "Runtime error handling and payload-size limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRuntimeContract" } } } } } } }, "/v1/agent-trust/sample-report": { "get": { "summary": "Sample Agent Trust Contract report", "description": "Public no-key sample report that scores K-Work Trust's own discovery contract so agents and operators can inspect the response shape before running an authenticated scan.", "security": [], "responses": { "200": { "description": "Sample agent trust contract report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrustCheckReport" } } } } } } }, "/v1/agent-trust/check": { "post": { "summary": "Agent Trust Contract pre-flight check", "description": "Authenticated scanner that checks whether another service exposes enough machine-readable discovery, readiness, auth, failure-mode, and first-safe-call contract information for autonomous agents. Remote fetches are limited to fixed public discovery paths and block localhost/private addresses by default.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrustCheckRequest" } } } }, "responses": { "200": { "description": "Agent trust contract report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrustCheckReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/AgentError" }, "429": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/provisional/challenge": { "get": { "summary": "Create an email-less provisional agent proof-of-work challenge", "security": [], "parameters": [ { "name": "agent_label", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One of agent_label, agent_id, or agent_url is required." }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "agent_url", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/AgentChallenge" }, "404": { "$ref": "#/components/responses/AgentError" }, "422": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/provisional": { "post": { "summary": "Issue an ultra-low-quota provisional key without email", "security": [], "requestBody": { "$ref": "#/components/requestBodies/AgentProvisionalIssue" }, "responses": { "201": { "description": "Provisional key issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProvisionalIssueResponse" } } } }, "403": { "$ref": "#/components/responses/AgentError" }, "409": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/provisional/upgrade/request-code": { "post": { "summary": "Request an email verification code to upgrade a provisional key", "requestBody": { "$ref": "#/components/requestBodies/AgentProvisionalUpgrade" }, "responses": { "202": { "description": "Verification code sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVerificationSentResponse" } } } }, "401": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/provisional/upgrade/verify": { "post": { "summary": "Verify email code and upgrade the same provisional key", "requestBody": { "$ref": "#/components/requestBodies/AgentCodeVerify" }, "responses": { "200": { "description": "Provisional key upgraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUpgradeResponse" } } } }, "401": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/request-code": { "post": { "summary": "Request an email verification code using a solved proof-of-work", "security": [], "requestBody": { "$ref": "#/components/requestBodies/AgentEmailRequestCode" }, "responses": { "202": { "description": "Verification code sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVerificationSentResponse" } } } }, "403": { "$ref": "#/components/responses/AgentError" } } } }, "/v1/agent/signup/verify": { "post": { "summary": "Verify email code and issue a low-quota agent API key", "security": [], "requestBody": { "$ref": "#/components/requestBodies/AgentCodeVerify" }, "responses": { "201": { "description": "Agent key issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeyIssuedResponse" } } } }, "401": { "$ref": "#/components/responses/AgentError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "requestBodies": { "VendorRecord": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorRecord" } } } }, "AgentProvisionalIssue": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProvisionalIssueRequest" } } } }, "AgentEmailRequestCode": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEmailRequestCodeRequest" } } } }, "AgentProvisionalUpgrade": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProvisionalUpgradeRequest" } } } }, "AgentCodeVerify": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCodeVerifyRequest" } } } } }, "schemas": { "VendorRecord": { "type": "object", "properties": { "registration_number": { "type": "string", "description": "Korean 10-digit business registration number." }, "company_name": { "type": "string" }, "address": { "type": "string" }, "phone_number": { "type": "string" }, "representative_name": { "type": "string" }, "email": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor_status": { "type": "string", "description": "Optional current vendor approval state, such as approved, active, needs_review, blocked, or inactive." }, "vendor_last_verified_at": { "type": "string", "description": "Optional ISO date/time when the vendor was last verified." }, "invoice_amount": { "type": "number" }, "currency": { "type": "string", "default": "KRW" }, "invoice_email": { "type": "string" }, "payment_due_date": { "type": "string" }, "payment_purpose": { "type": "string" }, "purchase_order_id": { "type": "string" }, "bank_account_holder": { "type": "string" }, "documents": { "type": "array", "description": "Document-derived field packets for document cross-checks. Use synthetic, public test, or authorized business data only.", "items": { "type": "object", "additionalProperties": true } }, "reverification_interval_days": { "type": "number", "default": 90 }, "reverification_grace_days": { "type": "number", "default": 15 }, "official_source_required": { "type": "boolean", "default": false }, "official_source_status": { "type": "string" }, "high_risk_flags": { "type": "array", "items": { "type": "string" } }, "check_opensanctions": { "type": "boolean", "description": "When true and KWT_OPENSANCTIONS_API_KEY is configured, run OpenSanctions matching for the submitted company or representative." }, "check_companies_house": { "type": "boolean", "description": "When true and KWT_COMPANIES_HOUSE_API_KEY is configured, request UK Companies House company profile evidence." }, "company_number": { "type": "string", "description": "UK Companies House company number for official company profile lookup." }, "companies_house_number": { "type": "string", "description": "Alias for the UK Companies House company number." }, "uk_company_number": { "type": "string", "description": "Alias for the UK Companies House company number." }, "opensanctions_dataset": { "type": "string", "default": "default" }, "opensanctions_threshold": { "type": "number", "default": 0.7 }, "action_type": { "type": "string", "description": "Proposed agent action category, such as local_docs_update, github_pr, external_post, production_deploy, or billing_change." }, "action_summary": { "type": "string" }, "target_resource": { "type": "string" }, "environment": { "type": "string", "description": "Target environment, such as local, staging, or production." }, "data_sensitivity": { "type": "string", "description": "Data class for the action, such as public, synthetic, internal, private, or sensitive." }, "risk_flags": { "type": "array", "items": { "type": "string" } }, "tests_passed": { "type": "boolean" }, "operator_approval_present": { "type": "boolean" }, "operator_approval_id": { "type": "string" }, "asset_type": { "type": "string", "description": "Technical asset type, such as api, mcp_server, github_repo, package, sdk, service, or tool." }, "target_name": { "type": "string" }, "target_url": { "type": "string" }, "repository_url": { "type": "string" }, "package_name": { "type": "string" }, "intended_use": { "type": "string" }, "readme_present": { "type": "boolean" }, "license_present": { "type": "boolean" }, "security_policy_present": { "type": "boolean" }, "tests_present": { "type": "boolean" }, "build_passed": { "type": "boolean" }, "ci_present": { "type": "boolean" }, "secret_scan_passed": { "type": "boolean" }, "dependency_scan_passed": { "type": "boolean" }, "dependency_risk": { "type": "string" }, "known_vulnerabilities": { "type": "array", "items": { "type": "string" } }, "openapi_present": { "type": "boolean" }, "mcp_manifest_present": { "type": "boolean" }, "mcp_tools_listed": { "type": "boolean" }, "skill_instructions_present": { "type": "boolean" }, "auth_policy_documented": { "type": "boolean" }, "quota_policy_documented": { "type": "boolean" }, "failure_modes_documented": { "type": "boolean" }, "first_safe_call_documented": { "type": "boolean" }, "writes_external_state": { "type": "boolean" }, "requires_secret": { "type": "boolean" }, "handles_sensitive_data": { "type": "boolean" }, "last_commit_at": { "type": "string" }, "evidence_items": { "type": "array", "items": { "type": "string" } }, "artifact_name": { "type": "string" }, "slsa_level": { "type": "number" }, "provenance_present": { "type": "boolean" }, "provenance_verified": { "type": "boolean" }, "signature_verified": { "type": "boolean" }, "digest_matches": { "type": "boolean" }, "sbom_present": { "type": "boolean" }, "source_pinned": { "type": "boolean" }, "builder_trusted": { "type": "boolean" }, "secret_sources": { "type": "array", "items": { "type": "string" } }, "secret_sinks": { "type": "array", "items": { "type": "string" } }, "taint_findings": { "type": "array", "items": { "type": "string" } }, "taint_analysis_passed": { "type": "boolean" }, "logs_redacted": { "type": "boolean" }, "secret_manager_used": { "type": "boolean" }, "public_outputs_redacted": { "type": "boolean" }, "breaking_changes": { "type": "array", "items": { "type": "string" } }, "removed_paths": { "type": "array", "items": { "type": "string" } }, "changed_schemas": { "type": "array", "items": { "type": "string" } }, "auth_changes": { "type": "array", "items": { "type": "string" } }, "invariants": { "type": "array", "items": { "type": "string" } }, "failed_invariants": { "type": "array", "items": { "type": "string" } }, "counterexamples": { "type": "array", "items": { "type": "string" } }, "test_cases_run": { "type": "number" }, "failure_count": { "type": "number" }, "crash_count": { "type": "number" }, "auth_bypass_count": { "type": "number" }, "schema_violation_count": { "type": "number" }, "data_leak_count": { "type": "number" }, "destructive_payloads_blocked": { "type": "boolean" }, "plan_id": { "type": "string" }, "goal": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "risk_tolerance": { "type": "number" }, "max_autonomous_risk": { "type": "number" }, "money_budget": { "type": "number" } }, "additionalProperties": true }, "ToolEnvelope": { "type": "object", "properties": { "request_id": { "type": "string" }, "tool": { "type": "string" }, "result": { "type": "object", "additionalProperties": true } } }, "ErrorEnvelope": { "type": "object", "properties": { "request_id": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after_seconds": { "type": "integer" }, "quota": { "type": "object", "additionalProperties": true }, "failure_mode": { "$ref": "#/components/schemas/AgentFailureMode" }, "retry": { "type": "string" }, "agent_next_action": { "type": "string" }, "escalation": { "type": "string" } }, "additionalProperties": true } }, "additionalProperties": true }, "AgentReadiness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready_for_agent_testing", "ready_for_invited_agents", "needs_operator_setup" ] }, "service": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "auth": { "type": "object", "additionalProperties": true }, "self_serve_signup": { "type": "object", "additionalProperties": true }, "official_sources": { "type": "object", "additionalProperties": true }, "storage": { "type": "object", "additionalProperties": true }, "recommended_flow": { "type": "array", "items": { "type": "string" } }, "first_call": { "type": "object", "additionalProperties": true }, "trust_contract_profiles": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTrustContractProfile" } }, "response_contract": { "$ref": "#/components/schemas/AgentResponseContract" }, "runtime_contract": { "$ref": "#/components/schemas/AgentRuntimeContract" }, "failure_modes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFailureMode" } }, "operator_actions_needed": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "AgentWhoami": { "type": "object", "properties": { "request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "authenticated", "anonymous_access_allowed" ] }, "service": { "type": "string" }, "client": { "type": "object", "additionalProperties": true }, "limits": { "type": "object", "additionalProperties": true }, "official_sources": { "type": "object", "additionalProperties": true }, "auth": { "type": "object", "additionalProperties": true }, "recommended_next_call": { "type": "object", "additionalProperties": true }, "response_contract": { "$ref": "#/components/schemas/AgentResponseContract" }, "runtime_contract": { "$ref": "#/components/schemas/AgentRuntimeContract" }, "failure_modes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFailureMode" } } }, "additionalProperties": true }, "AgentFailureMode": { "type": "object", "required": [ "code", "category", "retry", "agent_next_action", "escalation" ], "properties": { "code": { "type": "string" }, "applies_to": { "type": "array", "items": { "type": "string" } }, "http_status": { "type": "integer" }, "category": { "type": "string" }, "retry": { "type": "string" }, "agent_next_action": { "type": "string" }, "escalation": { "type": "string" }, "safe_to_log": { "type": "array", "items": { "type": "string" } }, "do_not_log": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "AgentResponseContract": { "type": "object", "properties": { "profile_id": { "type": "string" }, "success_fields": { "type": "array", "items": { "type": "string" } }, "decision_meanings": { "type": "object", "additionalProperties": { "type": "string" } }, "failure_mode_field": { "type": "string" }, "runtime_contract_field": { "type": "string" }, "escalation_contract": { "type": "string" }, "portable_fields": { "type": "array", "items": { "type": "string" } }, "domain_extensions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "AgentRuntimeContract": { "type": "object", "required": [ "schema_version", "errors_endpoint", "max_payload_size", "http_status_routing" ], "properties": { "schema_version": { "type": "string" }, "errors_endpoint": { "type": "string", "format": "uri" }, "max_payload_size": { "type": "object", "properties": { "request_body_bytes": { "type": "integer", "minimum": 1 }, "response_body_bytes": { "type": "integer", "minimum": 1 }, "tool_result_bytes": { "type": "integer", "minimum": 1 }, "agent_trust_fetch_bytes": { "type": "integer", "minimum": 1 }, "unit": { "type": "string", "enum": [ "bytes" ] } }, "additionalProperties": true }, "payload_size_policy": { "type": "string" }, "http_status_routing": { "type": "object", "additionalProperties": { "type": "string" } }, "required_public_error_fields": { "type": "array", "items": { "type": "string" } }, "failure_modes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFailureMode" } } }, "additionalProperties": true }, "AgentTrustContractProfile": { "type": "object", "required": [ "id", "status", "scope", "purpose" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "scope": { "type": "string", "enum": [ "portable", "domain_extension" ] }, "extends": { "type": "string" }, "purpose": { "type": "string" }, "required_public_surfaces": { "type": "array", "items": { "type": "string" } }, "required_contract_fields": { "type": "array", "items": { "type": "string" } }, "caller_decisions_supported": { "type": "array", "items": { "type": "string" } }, "domain_evidence_fields": { "type": "array", "items": { "type": "string" } }, "extension_rule": { "type": "string" }, "compatibility_rule": { "type": "string" } }, "additionalProperties": true }, "AgentProof": { "type": "object", "required": [ "challenge", "solution" ], "properties": { "challenge": { "type": "string", "description": "Opaque signed challenge returned by a signup challenge endpoint." }, "solution": { "type": "string", "maxLength": 160, "description": "Candidate proof-of-work solution." } }, "additionalProperties": false }, "AgentProofOfWorkContract": { "type": "object", "required": [ "algorithm", "digest_encoding", "input_template", "difficulty_rule", "solution_field", "challenge_field", "max_solution_length" ], "properties": { "algorithm": { "type": "string", "enum": [ "sha256" ] }, "digest_encoding": { "type": "string", "enum": [ "hex" ] }, "input_template": { "type": "string", "examples": [ "${nonce}:${subject}:${solution}" ] }, "difficulty_rule": { "type": "string" }, "solution_field": { "type": "string", "examples": [ "proof.solution" ] }, "challenge_field": { "type": "string", "examples": [ "proof.challenge" ] }, "max_solution_length": { "type": "integer", "minimum": 1, "examples": [ 160 ] }, "challenge_ttl_seconds": { "type": "integer", "minimum": 1 }, "email_signup_difficulty_hex_prefix_zeros": { "type": "integer", "minimum": 1 }, "provisional_signup_difficulty_hex_prefix_zeros": { "type": "integer", "minimum": 1 } }, "additionalProperties": true }, "AgentChallengeResponse": { "type": "object", "required": [ "status", "algorithm", "challenge", "nonce", "subject", "difficulty_hex_prefix_zeros", "proof_input_template", "proof_digest_prefix", "proof_max_solution_length", "proof_of_work", "request_endpoint" ], "properties": { "status": { "type": "string", "enum": [ "challenge" ] }, "algorithm": { "type": "string", "enum": [ "sha256" ] }, "challenge": { "type": "string" }, "nonce": { "type": "string" }, "subject": { "type": "string" }, "email": { "type": "string", "format": "email" }, "difficulty_hex_prefix_zeros": { "type": "integer", "minimum": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "proof_input_template": { "type": "string", "examples": [ "${nonce}:${subject}:${solution}" ] }, "proof_digest_prefix": { "type": "string", "examples": [ "0000" ] }, "proof_max_solution_length": { "type": "integer", "examples": [ 160 ] }, "proof_of_work": { "$ref": "#/components/schemas/AgentProofOfWorkContract" }, "solution_format": { "type": "string" }, "request_endpoint": { "type": "string" }, "request_code_endpoint": { "type": "string" } }, "additionalProperties": true }, "AgentProvisionalIssueRequest": { "type": "object", "required": [ "agent_label", "proof" ], "properties": { "agent_label": { "type": "string", "description": "Human-readable agent label." }, "agent_id": { "type": "string", "description": "Stable machine-readable agent identifier." }, "agent_url": { "type": "string", "description": "Agent profile, card, or manifest URL." }, "use_case": { "type": "string" }, "source_channel": { "type": "string", "examples": [ "moltbook" ] }, "campaign": { "type": "string" }, "proof": { "$ref": "#/components/schemas/AgentProof" } }, "additionalProperties": true }, "AgentProvisionalIssueResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "issued" ] }, "signup_mode": { "type": "string", "enum": [ "agent_provisional" ] }, "trust_level": { "type": "string", "enum": [ "provisional" ] }, "api_key": { "type": "string", "description": "Plaintext key returned once. Store securely and never expose publicly." }, "client_id": { "type": "string" }, "base_url": { "type": "string" }, "auth_header": { "type": "string" }, "rate_limit_rpm": { "type": "integer" }, "monthly_request_quota": { "type": "integer" }, "first_endpoint": { "type": "string" }, "warning": { "type": "string" } }, "additionalProperties": true }, "AgentEmailRequestCodeRequest": { "type": "object", "required": [ "email", "proof" ], "properties": { "email": { "type": "string", "format": "email" }, "agent_label": { "type": "string" }, "use_case": { "type": "string" }, "proof": { "$ref": "#/components/schemas/AgentProof" } }, "additionalProperties": true }, "AgentProvisionalUpgradeRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "agent_label": { "type": "string" }, "use_case": { "type": "string" } }, "additionalProperties": true }, "AgentCodeVerifyRequest": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } }, "additionalProperties": false }, "AgentVerificationSentResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verification_sent" ] }, "signup_mode": { "type": "string" }, "verify_endpoint": { "type": "string" } }, "additionalProperties": true }, "AgentKeyIssuedResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "issued" ] }, "signup_mode": { "type": "string" }, "api_key": { "type": "string", "description": "Plaintext key returned once. Store securely and never expose publicly." }, "client_id": { "type": "string" }, "rate_limit_rpm": { "type": "integer" }, "monthly_request_quota": { "type": "integer" }, "discovery": { "type": "object", "additionalProperties": true }, "agent_first_call": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "AgentUpgradeResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "upgraded" ] }, "signup_mode": { "type": "string", "enum": [ "agent_provisional_upgrade" ] }, "trust_level": { "type": "string", "enum": [ "email_verified" ] }, "client_id": { "type": "string" }, "auth_header": { "type": "string", "examples": [ "Authorization: Bearer " ] }, "rate_limit_rpm": { "type": "integer" }, "monthly_request_quota": { "type": "integer" } }, "additionalProperties": true }, "AgentSignupStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "service": { "type": "string" }, "base_url": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "mode": { "type": "string" }, "readiness_endpoint": { "type": "string" }, "whoami_endpoint": { "type": "string" }, "proof_secret_configured": { "type": "boolean" }, "proof_of_work": { "$ref": "#/components/schemas/AgentProofOfWorkContract" }, "rate_limits": { "type": "object", "additionalProperties": true }, "provisional": { "type": "object", "additionalProperties": true }, "email_verified": { "type": "object", "additionalProperties": true }, "key_policy": { "type": "object", "additionalProperties": true }, "failure_modes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFailureMode" } } }, "additionalProperties": true }, "AgentTrustCheckRequest": { "type": "object", "required": [ "base_url" ], "properties": { "base_url": { "type": "string", "format": "uri", "description": "Public http(s) base URL to inspect. Localhost and private network targets are blocked by default." }, "artifacts": { "type": "object", "description": "Optional pre-fetched artifacts for offline evaluation. Supported keys: health, manifest, readiness, runtime_errors, openapi, skill_md.", "additionalProperties": true } }, "additionalProperties": false }, "AgentTrustCheckReport": { "type": "object", "properties": { "request_id": { "type": "string" }, "service": { "type": "string", "enum": [ "agent-trust-contract-kit" ] }, "checked_at": { "type": "string", "format": "date-time" }, "base_url": { "type": "string" }, "result": { "type": "string", "enum": [ "usable_with_limits", "needs_minor_contract_work", "needs_operator_setup", "not_agent_ready" ] }, "safe_to_call": { "type": "string" }, "agent_contract_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "runtime_contract": { "$ref": "#/components/schemas/AgentRuntimeContract" }, "first_safe_call": { "type": "object", "additionalProperties": true }, "missing": { "type": "array", "items": { "type": "string" } }, "risks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recommended_next_action": { "type": "string" }, "checks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "evidence": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } }, "responses": { "ToolResponse": { "description": "Tool call envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolEnvelope" } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "AgentChallenge": { "description": "Proof-of-work challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentChallengeResponse" } } } }, "AgentError": { "description": "Signup error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }