{"openapi":"3.1.0","info":{"title":"AgentMetrix.ai API","version":"1.0.0","description":"Privacy-first analytics API for tracking, measuring, and optimizing non-human AI agent traffic. Identifies where agents bounce, why tool calls fail, and how to optimize schemas for the agentic web.","contact":{"name":"AgentMetrix.ai API Support","email":"api@agentmetrix.ai","url":"https://agentmetrix.ai/guide"},"license":{"name":"MIT","url":"https://agentmetrix.ai/legal"},"x-agent-readable":true,"x-llms-txt":"https://agentmetrix.ai/llms.txt","x-mcp-server":"https://mcp.agentmetrix.ai"},"servers":[{"url":"https://api.agentmetrix.ai/v1","description":"Production API"},{"url":"https://sandbox.api.agentmetrix.ai/v1","description":"Sandbox — for testing without real data"}],"security":[{"oauth2":["read:sessions"]}],"paths":{"/audit":{"post":{"operationId":"runAgentReadabilityAudit","summary":"Run an Agent Readability Audit on a URL","description":"Scans a given URL and returns an Agent Readability Score (0-100) with a breakdown of checks across API readability, llms.txt presence, MCP availability, OAuth configuration, checkout support, and AEO readiness. Returns a prioritized list of remediation steps.","x-agent-readable":true,"security":[{"oauth2":["read:sessions"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The documentation or API base URL to audit. Must be publicly accessible.","example":"https://docs.yourapi.com"},"depth":{"type":"string","enum":["quick","full"],"default":"quick","description":"Audit depth. 'quick' scans root-level files only (llms.txt, openapi.json, robots.txt). 'full' crawls up to 50 pages."}}}}}},"responses":{"200":{"description":"Audit completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResult"},"example":{"audit_id":"audit_9f2a3b4c5d","url":"https://docs.yourapi.com","overall_score":42,"grade":"C","checks":{"agent_readable_api":{"score":55,"status":"warn","issues":["14 endpoints missing descriptions"]},"llms_txt":{"score":0,"status":"fail","issues":["No /llms.txt file detected"]},"mcp_tools":{"score":0,"status":"fail","issues":["No MCP server endpoint detected"]},"oauth_config":{"score":40,"status":"warn","issues":["OAuth 2.0 detected, not 2.1","PKCE not enforced"]},"checkout_support":{"score":0,"status":"fail","issues":["No agentic payment protocol support"]},"aeo_schema":{"score":60,"status":"warn","issues":["FAQPage schema missing"]}},"top_issues":["No MCP server — agents cannot discover capabilities","Missing /llms.txt — AI agents waste context on HTML","OAuth 2.0 not 2.1 — PKCE not enforced"],"recommendation":"Add /llms.txt and expose an MCP endpoint to increase agent conversion rate by ~40-60%."}}}},"400":{"description":"Invalid URL or request parameters","content":{"application/json":{"example":{"error":"invalid_url","message":"The provided URL is not publicly accessible or returned a non-200 status.","retry_after":null}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"content":{"application/json":{"example":{"error":"rate_limit_exceeded","message":"Free tier allows 10 audits per day. Upgrade to Growth for 1,000/day.","retry_after":3600}}}}}}},"/sessions":{"post":{"operationId":"createAgentSession","summary":"Create an agent tracking session","description":"Creates a new session for tracking an AI agent's interactions with your API or documentation. Returns a session_id to embed in subsequent agent requests via the X-AgentMetrix-Session header.","x-agent-readable":true,"security":[{"oauth2":["write:sessions"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_model"],"properties":{"agent_model":{"type":"string","description":"The AI model identifier of the agent being tracked.","example":"claude-3-5-sonnet-20241022"},"acting_for":{"type":"string","description":"The user ID or identifier the agent is acting on behalf of.","example":"user_abc123"},"metadata":{"type":"object","description":"Optional key-value metadata to attach to the session.","additionalProperties":true}}}}}},"responses":{"201":{"description":"Session created","content":{"application/json":{"example":{"session_id":"sess_9f2a3b4c5d","created_at":"2026-06-06T01:15:21Z","expires_at":"2026-06-06T02:15:21Z","tracking_header":"X-AgentMetrix-Session: sess_9f2a3b4c5d"}}}}}}},"/sandbox/checkout":{"post":{"operationId":"runCheckoutSandboxTest","summary":"Test an agentic checkout flow in sandbox","description":"Simulates a complete agentic checkout flow using the specified payment protocol (ACP, AP2, x402, or MPP) without processing real payments. Returns a structured result including offer resolution, payment token exchange, order confirmation, and receipt generation. Use this to validate your checkout integration before going live.","x-agent-readable":true,"security":[{"oauth2":["write:sessions"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["protocol","product_url"],"properties":{"protocol":{"type":"string","enum":["ACP","AP2","x402","MPP"],"description":"The agentic payment protocol to test. ACP=Agentic Commerce Protocol (OpenAI/Stripe), AP2=Agent Payments Protocol (Google), x402=HTTP 402 stablecoin (Coinbase), MPP=Machine Payments Protocol (Stripe/Tempo)."},"product_url":{"type":"string","format":"uri","description":"The product detail page URL to test checkout against.","example":"https://yourstore.com/products/widget-pro"},"payment_token":{"type":"string","description":"Sandbox payment token. Use 'spt_test_sandbox_token' for ACP/MPP testing.","example":"spt_test_sandbox_token"}}}}}},"responses":{"200":{"description":"Checkout test completed","content":{"application/json":{"example":{"test_id":"test_checkout_7d8e9f","protocol":"ACP","status":"success","offer_resolution_ms":1240,"checkout_ms":3820,"order_id":"sandbox_ord_9f2a3b","total":{"amount":4999,"currency":"USD"},"receipt_id":"rcpt_sandbox_7d8e9f","issues":[]}}}}}}},"/api/ingest":{"post":{"operationId":"ingest_agent_event","summary":"Track an agent event with cost attribution","description":"Primary tracking endpoint. Accepts agent events with optional LLM token counts for cost computation. Checks circuit breaker rules and updates A2A relationship ledger. Returns 429 if a spend cap is triggered. Add X-AgentMetrix-* headers for A2A trace propagation.","x-agent-readable":true,"parameters":[{"name":"X-AgentMetrix-Agent-ID","in":"header","description":"Identifier for this agent","schema":{"type":"string"}},{"name":"X-AgentMetrix-Trace-ID","in":"header","description":"Unique trace ID for this hop","schema":{"type":"string"}},{"name":"X-AgentMetrix-Root-Trace-ID","in":"header","description":"Root trace ID grouping the full A2A chain","schema":{"type":"string"}},{"name":"X-AgentMetrix-Parent-Trace-ID","in":"header","description":"Parent hop trace ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["siteId","eventType"],"properties":{"siteId":{"type":"string","description":"Your AgentMetrix site ID","example":"site_123"},"eventType":{"type":"string","enum":["session_start","llm_call","tool_call","error","session_end"]},"provider":{"type":"string","description":"LLM provider for cost computation","example":"anthropic"},"model":{"type":"string","description":"LLM model name","example":"claude-sonnet-4-6"},"inputTokens":{"type":"integer","description":"Input/prompt token count","example":1250},"outputTokens":{"type":"integer","description":"Output/completion token count","example":340},"cachedTokens":{"type":"integer","description":"Cached input tokens (cheaper rate)","example":800}}}}}},"responses":{"200":{"description":"Event recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"traceId":{"type":"string"}}}}}},"429":{"description":"Circuit breaker triggered","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"spend_cap_exceeded"},"rule":{"type":"string"},"limitUsd":{"type":"string"}}}}}}}}},"/api/trpc/cost.calculateCost":{"get":{"operationId":"calculate_llm_cost","summary":"Calculate LLM cost for given token counts","description":"Returns exact cost in USD for a provider, model, and token count. Uses versioned pricing table covering 21 models. No authentication required.","x-agent-readable":true,"parameters":[{"name":"input","in":"query","required":true,"schema":{"type":"string","description":"JSON: {provider, model, inputTokens, outputTokens, cachedTokens}"}}],"responses":{"200":{"description":"Cost calculation","content":{"application/json":{"schema":{"type":"object","properties":{"costUsd":{"type":"string","example":"0.00750000"}}}}}}}}},"/api/trpc/aeoUpgrader.analyzeAndGenerate":{"post":{"operationId":"generate_aeo_documentation_upgrade","summary":"Generate AI-corrected API documentation","description":"Analyzes agent failure patterns for a URL and generates corrected OpenAPI specs, MCP manifests, or llms.txt files. Requires authentication.","x-agent-readable":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["json"],"properties":{"json":{"type":"object","required":["url","upgradeType"],"properties":{"url":{"type":"string","format":"uri"},"upgradeType":{"type":"string","enum":["openapi_patch","mcp_manifest","llms_txt","schema_fix"]}}}}}}}},"responses":{"200":{"description":"Generated upgrade","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string"},"diffSummary":{"type":"string"}}}}}}}}},"/receipts/{receipt_id}":{"get":{"operationId":"getAgentReceipt","summary":"Retrieve a structured agent receipt","description":"Returns the full structured audit trail for an agent transaction: the complete timeline of actions the agent took (schema reads, tool calls, OAuth flows, payment exchanges), the final transaction details, and a cryptographic signature for verification.","x-agent-readable":true,"security":[{"oauth2":["read:sessions"]}],"parameters":[{"name":"receipt_id","in":"path","required":true,"schema":{"type":"string"},"description":"The receipt identifier returned after a successful agent transaction.","example":"rcpt_7d8e9f2a3b"}],"responses":{"200":{"description":"Receipt retrieved","content":{"application/json":{"example":{"receipt_id":"rcpt_7d8e9f2a3b","session_id":"sess_9f2a3b4c5d","agent":{"model":"claude-3-5-sonnet-20241022","identity":"arn:aws:iam::123456789:role/shopping-agent","acting_for":"user_abc123"},"timeline":[{"ts":"2026-06-06T01:15:21Z","action":"GET /openapi.json","status":200,"latency_ms":87},{"ts":"2026-06-06T01:15:21Z","action":"PARSE_SCHEMA","fields_found":42},{"ts":"2026-06-06T01:15:22Z","action":"TOOL_CALL checkout","status":400,"error":"missing_field"},{"ts":"2026-06-06T01:15:22Z","action":"RETRY","attempt":2},{"ts":"2026-06-06T01:15:22Z","action":"CHECKOUT_CONFIRMED","order_id":"ord_9f2a3b"}],"payment":{"protocol":"ACP","amount":4999,"currency":"USD","merchant_order_id":"ord_9f2a3b"},"signature":"sha256:a1b2c3d4e5f6..."}}}},"404":{"description":"Receipt not found","content":{"application/json":{"example":{"error":"receipt_not_found","message":"No receipt found with the provided ID.","retry_after":null}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. All clients must use PKCE regardless of client type.","flows":{"authorizationCode":{"authorizationUrl":"https://auth.agentmetrix.ai/oauth/authorize","tokenUrl":"https://auth.agentmetrix.ai/oauth/token","scopes":{"read:sessions":"Read agent session data and events","write:sessions":"Create and update agent sessions","read:schema":"Read schema friction reports","write:schema":"Submit schemas for analysis","read:reports":"Access analytics reports and AEO scores"}}}}},"schemas":{"AuditResult":{"type":"object","properties":{"audit_id":{"type":"string","description":"Unique identifier for this audit run"},"url":{"type":"string","format":"uri"},"overall_score":{"type":"integer","minimum":0,"maximum":100,"description":"Agent Readability Score from 0 (completely unreadable) to 100 (fully agent-optimized)"},"grade":{"type":"string","enum":["A","B","C","D","F"]},"checks":{"type":"object","description":"Per-category scores and issues"},"top_issues":{"type":"array","items":{"type":"string"},"description":"Prioritized list of the most impactful issues to fix"},"recommendation":{"type":"string","description":"Plain-English summary recommendation from AgentMetrix"}}}}}}