{"openapi":"3.1.0","info":{"title":"Wake API","version":"1.0.0","description":"Read what AI agents did on your site, where they got stuck, what to fix, and how the listing is going. Every row is coarse by construction: daily HMAC nicknames, page classes, status codes, operator families, country codes. Never raw IP, user-agent, query, body, cookies or referrers."},"servers":[{"url":"https://agent-observatory-desk-production.up.railway.app"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Desk API key (wk_live_…), minted on the desk under Connect your AI."}}},"paths":{"/api/wake/v1/me":{"get":{"operationId":"wake_me","summary":"Desk identity","description":"Which site this key reads, whether it is verified and has a collector, and where the docs and MCP endpoint are.","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Desk identity","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/overview":{"get":{"operationId":"wake_overview","summary":"Overview","description":"Headline numbers for the window: events, sessions, unique agents, conversions, friction, by provider / class / intent / country, the funnel and the top friction.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Overview","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/agents":{"get":{"operationId":"wake_agents","summary":"Agents","description":"One row per agent nickname in the window (a nickname is a daily HMAC, so the same machine is a new row each UTC day), with sessions, stage reached, conversions and friction types.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Agents","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/sessions":{"get":{"operationId":"wake_sessions","summary":"Sessions","description":"Session rows (newest first): nickname, provider, class, timing, funnel stage, inferred intent, conversion, friction and the page classes touched. Filter by nickname; limit up to 500.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"description":"Max rows. Default 50."}},{"name":"nickname","in":"query","required":false,"schema":{"type":"string","description":"Only this agent nickname."}}],"responses":{"200":{"description":"Sessions","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/funnel":{"get":{"operationId":"wake_funnel","summary":"Funnel","description":"Cumulative funnel discovered → read_docs → authenticated → attempted_action → converted, with share of sessions and the biggest drop.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Funnel","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/friction":{"get":{"operationId":"wake_friction","summary":"Friction","description":"Where agents got stuck: friction kinds (auth_wall, action_unauthorized, action_rejected, action_server_error, repeated_error, abandoned_on_error, docs_dead_end) by page class with session counts, plus the fixes they imply.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Friction","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/fixes":{"get":{"operationId":"wake_fixes","summary":"Fixes","description":"Ranked, concrete changes to make the site navigable for agents: fixes derived from observed friction (with evidence counts) and readiness recommendations from the public probe of the site.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Fixes","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/alerts":{"get":{"operationId":"wake_alerts","summary":"Alerts","description":"What changed versus the previous window: spikes, new friction, conversion drops.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Alerts","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/series":{"get":{"operationId":"wake_series","summary":"Time series","description":"Per-hour (24h) or per-day buckets of events, sessions, agents, friction sessions and conversions, split by provider and class.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Time series","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/pages":{"get":{"operationId":"wake_pages","summary":"Pages & paths","description":"Page classes agents touched (home, docs, auth, pricing, checkout, account, search, api, discovery, other) and the most common sequences, each with conversion and friction counts.","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"Pages & paths","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/readiness":{"get":{"operationId":"wake_readiness","summary":"Readiness","description":"How the public site looks to an agent right now: homepage fetchability, robots.txt, llms.txt, sitemap, agent card, scores out of 100 and prioritised recommendations. Also returns ready-to-publish llms.txt and robots files.","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Readiness","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/listing":{"get":{"operationId":"wake_listing","summary":"Listing (AEO)","description":"The plan to bring more agents: discovery files to publish, the sensor door for this site, each listing step and its status, and arrivals judged by identified agents only (crawlers are counted separately, never as agents).","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Listing (AEO)","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/benchmarks":{"get":{"operationId":"wake_benchmarks","summary":"Benchmarks","description":"k-anonymous cohort medians (conversion, friction share) to compare against; withheld below k=5 sites.","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Benchmarks","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/scan":{"get":{"operationId":"wake_scan","summary":"Deep site scan","description":"How the public site answers named AI clients (GPTBot, ClaudeBot, PerplexityBot, a scripted client, a browser), the hosting stack, discovery files (llms.txt, agent card, MCP server card, OpenAPI), the site's shape by page class, docs without JavaScript, Markdown negotiation and transport. Structure only; no page text is kept. Cached 10 minutes.","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Deep site scan","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/playbook":{"get":{"operationId":"wake_playbook","summary":"AI setup playbook","description":"One Markdown file to hand to the AI tool that edits the site's codebase (Claude Code, Cursor, Codex): every change the scan calls for, with the exact files generated from the site's own pages, where they go on this stack, the ownership tag, the collector for this stack (with the real ingest key once the desk is verified and provisioned), and a curl to verify each step. Returns { markdown, prompt, tasks }.","security":[{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"AI setup playbook","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/install":{"get":{"operationId":"wake_install","summary":"Install status","description":"Whether ownership is verified and the collector is provisioned and reporting. With kit=true (verified desks only) returns the deploy-ready collector files for Cloudflare Workers, Express and Next.js, each already carrying the ingest key.","security":[{"bearer":[]}],"parameters":[{"name":"kit","in":"query","required":false,"schema":{"type":"boolean","description":"Include the collector files (verified desks only)."}}],"responses":{"200":{"description":"Install status","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/sessions.csv":{"get":{"operationId":"wake_sessions_csv","summary":"Sessions as CSV","security":[{"bearer":[]}],"parameters":[{"name":"window","in":"query","schema":{"type":"string","enum":["24h","7d","30d"],"description":"Time window. Default 7d."}}],"responses":{"200":{"description":"CSV","content":{"text/csv":{}}}}}},"/api/wake/v1/listing/plan":{"post":{"operationId":"wake_listing_plan","summary":"Prepare listing plan","description":"Prepare (never publish) the AEO listing plan for this site: discovery files and gated steps. Publishing stays an operator action.","security":[{"bearer":[]}],"responses":{"201":{"description":"Prepare listing plan"},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}}},"/api/wake/v1/public/readiness":{"get":{"operationId":"wake_public_readiness","summary":"Readiness of any public host (no auth)","parameters":[{"name":"host","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scores, recommendations, publish-ready files"}}}},"/api/wake/v1/public/mcp":{"post":{"operationId":"wake_public_mcp","summary":"Public MCP endpoint (no auth): wake_check_site, wake_about","responses":{"200":{"description":"JSON-RPC response"}}}},"/api/wake/v1/mcp":{"post":{"operationId":"wake_mcp","summary":"MCP endpoint (streamable HTTP)","description":"JSON-RPC 2.0 Model Context Protocol endpoint. Tools mirror the GET routes as wake_<name>. Use the same bearer key.","security":[{"bearer":[]}],"responses":{"200":{"description":"JSON-RPC response"}}}}}}