{ "openapi": "3.1.0", "info": { "title": "AgentWeb Runtime API", "version": "0.9.0", "description": "AgentWeb maps approved customer workflows into protocol-native action maps and exposes them through REST helpers and MCP tools. Use this API when an AI product needs reliable execution for authenticated or hard-to-verify web workflows.", "contact": { "name": "AgentWeb workflow mapping", "url": "https://calendly.com/andreymarey-work/30min", "email": "andrey@agentweb.us" } }, "servers": [ { "url": "https://mcp.agentweb.us", "description": "AgentWeb production runtime" }, { "url": "https://agentweb.us", "description": "AgentWeb public agent-discovery surface" }, { "url": "https://agentweb-telemetry.andreymarey20.workers.dev", "description": "AgentWeb privacy-preserving agent traffic telemetry" } ], "security": [ { "AgentWebApiKey": [] } ], "tags": [ { "name": "Discovery", "description": "Unauthenticated metadata for agents and integration scanners." }, { "name": "Runtime", "description": "Runtime endpoints for reading pages and discovering mapped workflows." }, { "name": "Onboarding", "description": "Agent-native registration and API key bootstrap." }, { "name": "MCP", "description": "MCP Streamable HTTP transport and public tool metadata." }, { "name": "Readiness", "description": "Public agent-readiness scanning and setup work-order generation." }, { "name": "Agent Traffic", "description": "Privacy-preserving attribution for agent-originated discovery and conversion events." }, { "name": "Billing", "description": "Stripe Checkout and usage-meter contracts for AgentWeb Network billing." }, { "name": "Payment Protocols", "description": "Machine payment metadata for MPP/x402-style agent payment discovery." }, { "name": "Policy", "description": "Policy, sandbox, action catalog, and schema map metadata for agents." } ], "paths": { "/health": { "get": { "tags": [ "Discovery" ], "summary": "Runtime health check", "description": "Returns runtime status and version. Agents may call this before attempting MCP or REST integration.", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Runtime is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "examples": { "ok": { "value": { "status": "ok", "version": "0.9.0" } } } } } } } } }, "/.well-known/mcp/server-card.json": { "get": { "tags": [ "Discovery", "MCP" ], "summary": "Public MCP server card", "description": "Machine-readable MCP server identity, auth model, tool manifest URL, and onboarding links. This endpoint is public so agents can understand AgentWeb before authenticating.", "operationId": "getMcpServerCard", "security": [], "responses": { "200": { "description": "MCP server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } } }, "/.well-known/mcp": { "get": { "tags": [ "Discovery", "MCP" ], "summary": "Well-known MCP discovery alias", "description": "Alias that returns the AgentWeb MCP server card with mcpUrl, serverUrl, transport, OAuth metadata, and public tool manifest links.", "operationId": "getMcpWellKnown", "security": [], "responses": { "200": { "description": "MCP server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } } }, "/.well-known/mcp.json": { "get": { "tags": [ "Discovery", "MCP" ], "summary": "Well-known MCP discovery JSON", "description": "JSON alias that exposes the AgentWeb MCP URL for scanners that probe /.well-known/mcp.json.", "operationId": "getMcpWellKnownJson", "security": [], "responses": { "200": { "description": "MCP server metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerCard" } } } } } } }, "/.well-known/mcp/tools.json": { "get": { "tags": [ "Discovery", "MCP" ], "summary": "Public MCP tool manifest", "description": "Lists safe metadata for AgentWeb MCP tools, including input schemas, output schemas, auth requirements, and example calls. Tool metadata is public; execution may require credentials.", "operationId": "getMcpTools", "security": [], "responses": { "200": { "description": "MCP tool metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolsManifest" } } } } } } }, "/api/read": { "get": { "tags": [ "Runtime" ], "summary": "Read a public page as structured content", "description": "Fetches a public URL and returns clean text, links, forms, and metadata. Use this instead of generic fetch when an agent needs structured web context.", "operationId": "readPage", "security": [], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public URL to fetch.", "schema": { "type": "string", "format": "uri" }, "example": "https://example.com/pricing" }, { "name": "selector", "in": "query", "required": false, "description": "Optional CSS selector for focused extraction.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Structured page content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageReadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamFailure" } } }, "post": { "tags": [ "Runtime" ], "summary": "Read a public page as structured content", "description": "POST variant for clients that prefer JSON request bodies.", "operationId": "readPagePost", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageReadRequest" }, "examples": { "pricing": { "value": { "url": "https://example.com/pricing", "selector": "main" } } } } } }, "responses": { "200": { "description": "Structured page content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageReadResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamFailure" } } } }, "/api/discover": { "get": { "tags": [ "Runtime" ], "summary": "Discover mapped workflow context for a domain", "description": "Returns AgentWeb's learned or curated action map context for a domain. Use before execution to determine whether a workflow is supported.", "operationId": "discoverDomain", "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "example": "example.com" } ], "responses": { "200": { "description": "Known map context or an explicit unmapped response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ActionMap" }, { "$ref": "#/components/schemas/DiscoverEmptyResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Runtime" ], "summary": "Discover mapped workflow context for a domain", "operationId": "discoverDomainPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverRequest" } } } }, "responses": { "200": { "description": "Known map context or an explicit unmapped response.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ActionMap" }, { "$ref": "#/components/schemas/DiscoverEmptyResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/register": { "post": { "tags": [ "Onboarding" ], "summary": "Start agent-native API key registration", "description": "Sends a verification code to the provided email and returns a deviceId needed for /api/verify. This allows compatible agents to bootstrap API access without guessing the signup flow.", "operationId": "registerEmail", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" }, "examples": { "email": { "value": { "email": "operator@example.com" } } } } } }, "responses": { "200": { "description": "Verification code sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/verify": { "post": { "tags": [ "Onboarding" ], "summary": "Verify registration and return API key", "description": "Verifies an email code and returns an AgentWeb API key plus MCP setup command when provisioning is available.", "operationId": "verifyEmail", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" }, "examples": { "code": { "value": { "email": "operator@example.com", "code": "123456", "deviceId": "6f86a0d4-4f91-42e6-8cf6-8bf8922d64aa" } } } } } }, "responses": { "200": { "description": "Email verified and credentials returned or dashboard fallback supplied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/mcp": { "post": { "tags": [ "MCP" ], "summary": "MCP Streamable HTTP endpoint", "description": "Handles MCP Streamable HTTP requests. Unauthenticated callers receive OAuth/protected-resource discovery hints. Use /.well-known/mcp/tools.json for unauthenticated tool metadata.", "operationId": "mcp", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "MCP response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Authentication required. See WWW-Authenticate and OAuth metadata.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge containing resource metadata URL." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/readiness/scan": { "post": { "tags": [ "Readiness" ], "summary": "Scan a business for agent discoverability and executionability", "description": "Dispatches deterministic public-surface scan workers. The scanner fetches only public metadata and returns scores, action candidates, setup scopes, payment-path recommendation, work order, and telemetry context. It does not submit forms, collect credentials, touch private accounts, or initiate payment.", "operationId": "scanAgentReadiness", "servers": [ { "url": "https://agentweb.us" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessScanRequest" }, "examples": { "scan": { "value": { "url": "https://example.com", "session_id": "5d87c8e2-0f16-46ef-9cc1-9b0cc742f441", "agent_protocol": "a2a", "discovery_surface": "a2a_agent_card", "payment_session_intent": "quote", "scan_authorization": true, "agent": { "name": "partner-agent", "provider": "example" } } } } } } }, "responses": { "200": { "description": "Agent readiness report and setup work order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessScanResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/telemetry/agent-event": { "post": { "tags": [ "Agent Traffic" ], "summary": "Record an agent-originated attribution event", "description": "Records how an agent discovered AgentWeb, which protocol and discovery surface it used, what business it asked about, and the conversion state. Raw prompts, raw IPs, payment credentials, and private customer payloads are not stored.", "operationId": "recordAgentTrafficEvent", "servers": [ { "url": "https://agentweb-telemetry.andreymarey20.workers.dev" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrafficEvent" }, "examples": { "event": { "value": { "event_id": "evt_123", "session_id": "5d87c8e2-0f16-46ef-9cc1-9b0cc742f441", "agent_protocol": "a2a", "discovery_surface": "a2a_agent_card", "task_type": "agent_readiness_scan", "business_domain": "example.com", "conversion_state": "scan_requested", "privacy_redactions": [ "ip_hashed_server_side", "raw_prompt_not_stored", "payment_details_not_stored" ] } } } } } }, "responses": { "200": { "description": "Event recorded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/billing/create-checkout-session": { "post": { "tags": [ "Billing" ], "summary": "Create a Stripe Checkout subscription session", "description": "Creates a Stripe Checkout session for design-partner or AgentWeb Network billing. The agent_network plan subscribes the customer to a base platform price plus configured metered usage prices and hard-requires scoped paymentAuthority before Stripe Checkout is created. External agents should call this only after price_setup returns terms and the customer has approved authority with create.checkout_session scope, amount limit, currency, expiry, revocation URL, receipt requirement, and verification requirement. Server-to-server agent callers may omit a browser Origin header; browser requests with explicit origins remain restricted to AgentWeb allowed origins. Do not expose raw Stripe keys, unrestricted Stripe tools, credentials, prompts, raw page bodies, or private payloads to this endpoint.", "operationId": "createBillingCheckoutSession", "servers": [ { "url": "https://agentweb.us" } ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutRequest" }, "examples": { "agentNetwork": { "value": { "email": "ops@example.com", "plan": "agent_network", "partnerName": "Example Co", "businessDomain": "example.com", "agentProvider": "claude_code", "agentProtocol": "a2a", "agentSessionId": "session_123", "paymentAuthority": { "authority_id": "auth_123", "principal": { "type": "business", "id": "example_co", "agent_provider": "claude_code" }, "scope": [ "price.setup", "create.checkout_session" ], "amount_limit": { "value": 500000, "interval": "single_use" }, "currency": "usd", "expires_at": "2026-05-08T00:00:00Z", "revocation_url": "https://example.com/agent-authority/auth_123/revoke", "receipt_required": true, "verification_required": true, "created_at": "2026-05-01T00:00:00Z" } } } } } } }, "responses": { "200": { "description": "Stripe Checkout session URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingCheckoutResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Payment authority or paid setup is required before checkout/session creation.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Machine-readable payment requirement signal for x402-compatible clients." }, "x-payment-info": { "schema": { "type": "string", "format": "uri" }, "description": "Payment protocol metadata URL." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-payment-info": "https://agentweb.us/.well-known/payment-protocols.json" } }, "/api/billing/report-meter-event": { "post": { "tags": [ "Billing" ], "summary": "Record internal usage into Stripe Billing meters", "description": "Internal-only endpoint for AgentWeb services to report billable usage to Stripe meter events. It accepts only approved event names and dimensions, and must never receive prompts, credentials, payment details, private customer payloads, or page bodies.", "operationId": "reportBillingMeterEvent", "servers": [ { "url": "https://agentweb.us" } ], "security": [ { "BillingEventSecret": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingMeterEventRequest" }, "examples": { "scanUsage": { "value": { "stripe_customer_id": "cus_123", "event_name": "agentweb_readiness_scan", "value": 1, "identifier": "scan_2026_05_01_example_001", "dimensions": { "business_domain": "example.com", "agent_platform": "claude_code", "agent_protocol": "a2a", "discovery_surface": "agent_card" } } } } } } }, "responses": { "200": { "description": "Meter event accepted by Stripe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingMeterEventResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/billing/webhook": { "post": { "tags": [ "Billing" ], "summary": "Receive Stripe webhook events and fulfill paid entitlements", "description": "Stripe-only webhook endpoint. Verifies Stripe-Signature before parsing the event, records event IDs for idempotency, grants or revokes Supabase profile entitlements from subscription/payment events, and logs meter validation errors. External agents must never call this endpoint.", "operationId": "handleStripeBillingWebhook", "servers": [ { "url": "https://agentweb.us" } ], "security": [ { "StripeWebhookSignature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeWebhookEvent" } } } }, "responses": { "200": { "description": "Webhook verified and accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeWebhookResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/UpstreamFailure" } } } }, "/.well-known/action-catalog.json": { "get": { "tags": [ "Discovery", "Policy" ], "summary": "Public action catalog", "description": "Lists allowed and disallowed AgentWeb action families, fields, auth requirements, payment rules, and verification semantics.", "operationId": "getActionCatalog", "security": [], "responses": { "200": { "description": "Action catalog.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/sandbox.json": { "get": { "tags": [ "Discovery", "Policy" ], "summary": "Public sandbox metadata", "description": "Self-serve and sandbox signals for public scans, tool metadata, registration, and setup limits.", "operationId": "getSandboxMetadata", "security": [], "responses": { "200": { "description": "Sandbox metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/mpp.json": { "get": { "tags": [ "Discovery", "Payment Protocols" ], "summary": "MPP payment profile", "description": "Machine Payments Protocol-style metadata for AgentWeb setup, map generation, verification, and metered usage. Stripe Checkout/Billing remains the settlement rail.", "operationId": "getMppProfile", "security": [], "responses": { "200": { "description": "MPP metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/x402.json": { "get": { "tags": [ "Discovery", "Payment Protocols" ], "summary": "x402 payment profile", "description": "x402-compatible payment requirement metadata for agents evaluating paid AgentWeb endpoints.", "operationId": "getX402Profile", "security": [], "responses": { "200": { "description": "x402 metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/discovery/resources": { "get": { "tags": [ "Discovery", "Payment Protocols" ], "summary": "x402 discovery resources", "description": "x402-style discovery resources for paid AgentWeb endpoints. Responses include PAYMENT-REQUIRED and x-payment-info headers on the live route.", "operationId": "getX402DiscoveryResources", "security": [], "responses": { "200": { "description": "x402 discovery resources.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Indicates the listed endpoint requires payment authority." }, "x-payment-info": { "schema": { "type": "string", "format": "uri" }, "description": "Payment protocol metadata URL." } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/.well-known/api-catalog": { "get": { "tags": [ "Discovery" ], "summary": "RFC 9727 API catalog linkset", "description": "Linkset catalog of AgentWeb OpenAPI, MCP, action catalog, and payment protocol resources.", "operationId": "getApiCatalog", "security": [], "responses": { "200": { "description": "API catalog linkset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linkset" ], "properties": { "linkset": { "type": "array" } }, "additionalProperties": true } } } } } } }, "/.well-known/http-message-signatures-directory": { "get": { "tags": [ "Discovery", "Policy" ], "summary": "HTTP Message Signatures directory", "description": "Web Bot Auth compatible public signing-key directory for AgentWeb-originated agent discovery messages.", "operationId": "getHttpMessageSignaturesDirectory", "security": [], "responses": { "200": { "description": "HTTP message signatures directory.", "content": { "application/json": { "schema": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array" } }, "additionalProperties": true } } } } } } }, "/.well-known/schemamap.xml": { "get": { "tags": [ "Discovery" ], "summary": "NLWeb schema map", "description": "XML schema map linking AgentWeb OpenAPI, action-map, payment, readiness, and setup schemas.", "operationId": "getSchemaMap", "security": [], "responses": { "200": { "description": "Schema map XML.", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/.well-known/mcp/apps.json": { "get": { "tags": [ "Discovery", "MCP" ], "summary": "Public MCP Apps manifest", "description": "MCP Apps resources and recommended AgentWeb tools for setup, delegated auth, payment authority, and verification flows.", "operationId": "getMcpAppsManifest", "security": [], "responses": { "200": { "description": "MCP Apps metadata.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } }, "components": { "securitySchemes": { "AgentWebApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "aw_", "description": "Use Authorization: Bearer aw_. Design partner keys are issued after workflow mapping. OAuth bootstrap may issue awo_ tokens for compatible MCP clients.", "x-scopes": { "scan.public": "Run public readiness scans.", "read.public": "Read public pages and metadata.", "actions.list": "List approved mapped actions.", "actions.execute": "Execute approved mapped actions.", "setup.create": "Request Agent Map setup.", "payment.quote": "Read setup and usage pricing.", "create.checkout_session": "Create Stripe Checkout with scoped payment authority.", "verification.read": "Read receipt, status, or setup proof." } }, "BillingEventSecret": { "type": "http", "scheme": "bearer", "description": "Internal AgentWeb billing-event secret. This is not an end-user or external-agent credential." }, "StripeWebhookSignature": { "type": "apiKey", "in": "header", "name": "Stripe-Signature", "description": "Stripe webhook signature. AgentWeb verifies this before parsing or fulfilling any Stripe event." } }, "responses": { "BadRequest": { "description": "Invalid or missing request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until retry is recommended." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "rateLimited": { "value": { "error": "Rate limit exceeded. Max 60 requests per hour." } } } } } }, "UpstreamFailure": { "description": "The target URL could not be fetched or parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden origin or caller.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Missing or invalid authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string" } } }, "PageReadRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "selector": { "type": "string" } } }, "PageReadResponse": { "type": "object", "required": [ "title", "text", "links", "forms", "metadata" ], "properties": { "title": { "type": "string" }, "text": { "type": "string" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/PageLink" } }, "forms": { "type": "array", "items": { "$ref": "#/components/schemas/PageForm" } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "PageLink": { "type": "object", "properties": { "text": { "type": "string" }, "href": { "type": "string" }, "rel": { "type": "string" } }, "additionalProperties": true }, "PageForm": { "type": "object", "properties": { "action": { "type": "string" }, "method": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "DiscoverRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" } } }, "DiscoverEmptyResponse": { "type": "object", "required": [ "domain", "message" ], "properties": { "domain": { "type": "string" }, "message": { "type": "string" } } }, "ActionMap": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "auth_model": { "type": "object", "additionalProperties": true }, "verification": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "RegisterRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "RegisterResponse": { "type": "object", "required": [ "ok", "deviceId", "message" ], "properties": { "ok": { "type": "boolean" }, "deviceId": { "type": "string" }, "message": { "type": "string" } } }, "VerifyRequest": { "type": "object", "required": [ "email", "code", "deviceId" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string" }, "deviceId": { "type": "string" } } }, "VerifyResponse": { "type": "object", "required": [ "ok", "verified", "mcp_url", "message" ], "properties": { "ok": { "type": "boolean" }, "verified": { "type": "boolean" }, "api_key": { "type": "string", "description": "Returned once when provisioning succeeds." }, "mcp_url": { "type": "string", "format": "uri" }, "setup_command": { "type": "string" }, "message": { "type": "string" } } }, "McpServerCard": { "type": "object", "required": [ "name", "description", "url", "transport", "auth", "tool_manifest" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "transport": { "type": "string" }, "auth": { "type": "object", "additionalProperties": true }, "tools": { "type": "array", "items": { "type": "string" } }, "tool_manifest": { "type": "string", "format": "uri" }, "docs": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "McpToolsManifest": { "type": "object", "required": [ "name", "server", "transport", "tools" ], "properties": { "name": { "type": "string" }, "server": { "type": "string", "format": "uri" }, "transport": { "type": "string" }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpTool" } } } }, "McpTool": { "type": "object", "required": [ "name", "description", "auth", "input_schema" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "auth": { "type": "string", "enum": [ "none", "optional", "api_key", "oauth" ] }, "input_schema": { "type": "object", "additionalProperties": true }, "output_schema": { "type": "object", "additionalProperties": true }, "example": { "type": "object", "additionalProperties": true } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "ReadinessScanRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "session_id": { "type": "string", "description": "Stable per agent/customer attempt when available." }, "agent_protocol": { "type": "string", "enum": [ "a2a", "mcp", "openapi", "direct_api", "human_web", "unknown" ] }, "discovery_surface": { "type": "string", "enum": [ "a2a_agent_card", "mcp_registry", "openapi_spec", "llms_txt", "agents_json", "web_search", "direct_api", "human_web", "partner_referral", "unknown" ] }, "payment_session_intent": { "type": "string", "enum": [ "quote", "none" ] }, "scan_authorization": { "type": "boolean", "description": "Confirms the caller is requesting public-surface scanning only." }, "agent": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "Optional pseudonymous agent ID. Server hashes before storage." }, "name": { "type": "string" }, "provider": { "type": "string" } } } }, "additionalProperties": true }, "ReadinessScanResponse": { "type": "object", "required": [ "hostname", "score", "grade", "agent_runs", "telemetry_context", "privacy_and_scope_review" ], "properties": { "scanned_at": { "type": "string", "format": "date-time" }, "hostname": { "type": "string" }, "score": { "type": "number" }, "grade": { "type": "string" }, "agent_discoverability_score": { "type": "number" }, "agent_executionability_score": { "type": "number" }, "summary": { "type": "string" }, "surfaces": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_runs": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "workflow_candidates": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "agent_work_order": { "type": "object", "additionalProperties": true }, "endpoint_map_requirements": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "setup_session_offer": { "type": "object", "additionalProperties": true }, "recommended_payment_path": { "type": "object", "additionalProperties": true }, "telemetry_context": { "$ref": "#/components/schemas/AgentTrafficEvent" }, "privacy_and_scope_review": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "AgentTrafficEvent": { "type": "object", "required": [ "session_id", "agent_protocol", "discovery_surface", "conversion_state", "privacy_redactions" ], "properties": { "event_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "session_id": { "type": "string" }, "agent_id": { "type": "string", "description": "Optional pseudonymous ID; server stores a hash." }, "agent_name": { "type": "string" }, "agent_provider": { "type": "string" }, "agent_protocol": { "type": "string" }, "discovery_surface": { "type": "string" }, "entry_url": { "type": "string" }, "landing_capability": { "type": "string" }, "task_type": { "type": "string" }, "business_domain": { "type": "string" }, "package_quoted": { "type": "string" }, "payment_state": { "type": "string" }, "conversion_state": { "type": "string" }, "referrer": { "type": "string" }, "host": { "type": "string" }, "privacy_redactions": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true }, "BillingCheckoutRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "plan": { "type": "string", "enum": [ "design_partner", "agent_network", "pro" ], "default": "design_partner" }, "partnerName": { "type": "string" }, "businessDomain": { "type": "string" }, "agentProvider": { "type": "string" }, "agentProtocol": { "type": "string", "enum": [ "a2a", "mcp", "openapi", "direct_api", "human_web", "unknown" ] }, "agentSessionId": { "type": "string", "description": "Optional pseudonymous session ID for attribution. Do not send raw prompts or private user data." }, "paymentAuthority": { "description": "Required for agent_network checkout. Must include create.checkout_session scope, principal, positive amount limit, currency, future expiry, revocation URL, receipt_required=true, and verification_required=true. AgentWeb stores only bounded authority metadata in Stripe.", "oneOf": [ { "$ref": "#/components/schemas/PaymentAuthority" }, { "$ref": "#/components/schemas/PaymentAuthorityMetadata" } ] } }, "additionalProperties": false }, "BillingCheckoutResponse": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } }, "BillingMeterEventRequest": { "type": "object", "required": [ "stripe_customer_id", "event_name", "value" ], "properties": { "stripe_customer_id": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$" }, "event_name": { "type": "string", "enum": [ "agentweb_readiness_scan", "agentweb_action_map_generation", "agentweb_verified_action", "agentweb_setup_session" ] }, "value": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "identifier": { "type": "string", "maxLength": 100, "description": "Idempotency identifier for this usage event." }, "timestamp": { "type": "integer", "description": "Unix seconds. Must be within Stripe meter event bounds." }, "dimensions": { "type": "object", "additionalProperties": false, "properties": { "business_domain": { "type": "string" }, "agent_platform": { "type": "string" }, "agent_protocol": { "type": "string" }, "discovery_surface": { "type": "string" }, "package": { "type": "string" }, "event_type": { "type": "string" } } } }, "additionalProperties": false }, "BillingMeterEventResponse": { "type": "object", "required": [ "recorded", "event_name", "identifier" ], "properties": { "recorded": { "type": "boolean" }, "event_name": { "type": "string" }, "identifier": { "type": "string" }, "timestamp": { "type": "integer" } } }, "PaymentAuthority": { "title": "AgentWeb Payment Authority", "description": "A scoped authority artifact that lets an agent request paid AgentWeb setup or execution without receiving raw payment credentials.", "type": "object", "required": [ "authority_id", "principal", "scope", "amount_limit", "currency", "expires_at", "revocation_url", "receipt_required", "verification_required", "created_at" ], "properties": { "authority_id": { "type": "string" }, "principal": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "user", "business", "agent", "enterprise_account" ] }, "id": { "type": "string" }, "agent_provider": { "type": "string" }, "authority_reference": { "type": "string" } }, "additionalProperties": false }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "scan.public_site", "price.setup", "create.checkout_session", "create.setup_session", "generate.action_map_draft", "verify.install", "execute.approved_action" ] }, "minItems": 1 }, "amount_limit": { "type": "object", "required": [ "value" ], "description": "Maximum spend approved for the scoped AgentWeb task. Value is expressed in the smallest currency unit, such as cents for USD.", "properties": { "value": { "type": "integer", "minimum": 1 }, "interval": { "type": "string", "enum": [ "single_use", "daily", "monthly", "setup_session" ] } }, "additionalProperties": false }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "expires_at": { "type": "string", "format": "date-time" }, "revocation_url": { "type": "string", "format": "uri" }, "receipt_required": { "type": "boolean", "default": true }, "verification_required": { "type": "boolean", "default": true }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PaymentAuthorityMetadata": { "type": "object", "description": "Bounded, non-sensitive payment authority metadata accepted by the checkout endpoint. Use this only when the caller does not have the full PaymentAuthority artifact shape.", "additionalProperties": false, "properties": { "authority_reference": { "type": "string", "description": "Opaque reference to an approval artifact or customer-controlled authority record." }, "principal_type": { "type": "string", "enum": [ "user", "business", "agent", "enterprise_account" ] }, "scope": { "type": "array", "items": { "type": "string" } }, "amount_limit_cents": { "type": "integer", "minimum": 1, "description": "Maximum approved spend in the smallest currency unit, such as cents for USD." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "expires_at": { "type": "string", "format": "date-time" } } }, "StripeWebhookResponse": { "type": "object", "required": [ "received" ], "properties": { "received": { "type": "boolean" }, "duplicate": { "type": "boolean", "description": "True when the Stripe event ID was already processed." } }, "additionalProperties": false }, "StripeWebhookEvent": { "type": "object", "description": "Stripe event payload delivered by Stripe. This endpoint is for Stripe only, not for external agents.", "required": [ "id", "type", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "livemode": { "type": "boolean" }, "data": { "type": "object" } }, "additionalProperties": true } } }, "externalDocs": { "description": "AgentWeb full agent reference", "url": "https://agentweb.us/llms-full.txt" } }