{"openapi":"3.1.0","info":{"title":"Heedeo public API","version":"0.1.0","summary":"Book a demo to get Heedeo, and see how heedeo.com classifies your request.","description":"Heedeo is ready. It judges every call by what it does, not what it is: it recognises AI agents on a site, works out which account or passkey each acts for, and applies per-route rules in the site's middleware: allow, challenge, restrict (verdict `throttle`) or block. People book a demo at https://cal.com/heedeo/30min?utm_source=heedeo.com&utm_medium=site and the team sets them up. Agents can request a call for the person they work for with POST /api/book. Agent requests stay pending until the person confirms, by booking themselves or when the team checks with them.","contact":{"url":"https://heedeo.com"}},"servers":[{"url":"https://heedeo.com"}],"externalDocs":{"description":"The whole site as markdown","url":"https://heedeo.com/index.md"},"paths":{"/api/book":{"post":{"operationId":"bookCall","summary":"Book a demo to get access to Heedeo","description":"Requests a short call to get access to Heedeo. After the call the team sets you up. A person's request is confirmed right away. When `via` is `agent`, or the request looks like it comes from an agent, it stays pending until the person confirms, by booking themselves or when the team checks with them. Plain scripts such as curl or python-requests count as agents. A repeat request for the same email is not an error: it returns 200 and says where things stand.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookRequest"},"examples":{"agent":{"summary":"An agent requesting a call for the person it works for","value":{"email":"maya@acme.co","site":"acme.co","pain":"agents farming free trials","via":"agent","agent":"ChatGPT agent"}},"human":{"summary":"A person requesting a call","value":{"email":"maya@acme.co"}}}}}},"responses":{"200":{"description":"Request recorded, or already recorded. `message` says what happens next.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookResponse"},"examples":{"agentPending":{"summary":"A new request from an agent","value":{"ok":true,"position":null,"existing":false,"status":"pending","message":"Request received. We'll email maya@acme.co to confirm and book the call."}},"agentExistingPending":{"summary":"Already requested, still pending","value":{"ok":true,"position":null,"existing":true,"status":"pending","message":"Already requested, pending. We'll email them to confirm and book the call."}},"agentRepeat":{"summary":"An agent requested a call for the same email in the last 24 hours","value":{"ok":true,"position":null,"existing":true,"status":"pending","message":"Already requested, pending. We'll email them to confirm and book the call. No need to try again."}},"agentConfirmed":{"summary":"An agent asks about a person who already confirmed","value":{"ok":true,"position":null,"existing":true,"status":"confirmed","message":"Already requested and confirmed by the person. Nothing else to do."}},"human":{"summary":"A person requests a call","value":{"ok":true,"position":142,"existing":false,"status":"confirmed","message":"Thanks. We'll email you to book your call."}},"humanRepeat":{"summary":"A person requests again","value":{"ok":true,"position":null,"existing":true,"status":"confirmed","message":"We already have your request. We'll email you to book your call."}},"humanAfterAgent":{"summary":"The person requests after their agent did, and is promoted to confirmed","value":{"ok":true,"position":143,"existing":true,"status":"confirmed","message":"Thanks. We'll email you to book your call."}}}}}},"400":{"description":"The body isn't a JSON object, the email doesn't look right, `via` isn't `human` or `agent`, or `site`, `pain` or `agent` isn't a string.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"email":{"value":{"ok":false,"error":"That email doesn't look right."}},"via":{"value":{"ok":false,"error":"\"via\" must be \"human\" or \"agent\"."}},"site":{"value":{"ok":false,"error":"\"site\" must be a string."}},"pain":{"value":{"ok":false,"error":"\"pain\" must be a string."}},"agent":{"value":{"ok":false,"error":"\"agent\" must be a string."}}}}}},"500":{"description":"Something broke on our side. Try again.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"What went wrong, in plain words.","examples":["Something went wrong. Please try again."]}}}}}}}},"get":{"operationId":"bookGetNotAllowed","summary":"Not supported. Use POST.","description":"GET is not supported on this path. It returns 405 with an `Allow: POST` header.","responses":{"405":{"description":"Method not allowed. Use POST with a JSON body.","headers":{"Allow":{"description":"The methods this path accepts.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"What went wrong, in plain words.","examples":["Use POST with a JSON body. The full description is at https://heedeo.com/openapi.json."]}}}}}}}}},"/api/waitlist":{"post":{"operationId":"joinWaitlist","summary":"Deprecated alias of POST /api/book","deprecated":true,"description":"Deprecated. Use POST /api/book. Same handler, body and responses, and it still works.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookRequest"},"examples":{"agent":{"summary":"An agent requesting a call for the person it works for","value":{"email":"maya@acme.co","site":"acme.co","pain":"agents farming free trials","via":"agent","agent":"ChatGPT agent"}},"human":{"summary":"A person requesting a call","value":{"email":"maya@acme.co"}}}}}},"responses":{"200":{"description":"Request recorded, or already recorded. `message` says what happens next.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookResponse"},"examples":{"agentPending":{"summary":"A new request from an agent","value":{"ok":true,"position":null,"existing":false,"status":"pending","message":"Request received. We'll email maya@acme.co to confirm and book the call."}},"agentExistingPending":{"summary":"Already requested, still pending","value":{"ok":true,"position":null,"existing":true,"status":"pending","message":"Already requested, pending. We'll email them to confirm and book the call."}},"agentRepeat":{"summary":"An agent requested a call for the same email in the last 24 hours","value":{"ok":true,"position":null,"existing":true,"status":"pending","message":"Already requested, pending. We'll email them to confirm and book the call. No need to try again."}},"agentConfirmed":{"summary":"An agent asks about a person who already confirmed","value":{"ok":true,"position":null,"existing":true,"status":"confirmed","message":"Already requested and confirmed by the person. Nothing else to do."}},"human":{"summary":"A person requests a call","value":{"ok":true,"position":142,"existing":false,"status":"confirmed","message":"Thanks. We'll email you to book your call."}},"humanRepeat":{"summary":"A person requests again","value":{"ok":true,"position":null,"existing":true,"status":"confirmed","message":"We already have your request. We'll email you to book your call."}},"humanAfterAgent":{"summary":"The person requests after their agent did, and is promoted to confirmed","value":{"ok":true,"position":143,"existing":true,"status":"confirmed","message":"Thanks. We'll email you to book your call."}}}}}},"400":{"description":"The body isn't a JSON object, the email doesn't look right, `via` isn't `human` or `agent`, or `site`, `pain` or `agent` isn't a string.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"email":{"value":{"ok":false,"error":"That email doesn't look right."}},"via":{"value":{"ok":false,"error":"\"via\" must be \"human\" or \"agent\"."}},"site":{"value":{"ok":false,"error":"\"site\" must be a string."}},"pain":{"value":{"ok":false,"error":"\"pain\" must be a string."}},"agent":{"value":{"ok":false,"error":"\"agent\" must be a string."}}}}}},"500":{"description":"Something broke on our side. Try again.","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"What went wrong, in plain words.","examples":["Something went wrong. Please try again."]}}}}}}}},"get":{"operationId":"waitlistGetNotAllowed","deprecated":true,"summary":"Not supported. Use POST.","description":"GET is not supported on this path. It returns 405 with an `Allow: POST` header.","responses":{"405":{"description":"Method not allowed. Use POST with a JSON body.","headers":{"Allow":{"description":"The methods this path accepts.","schema":{"type":"string","const":"POST"}}},"content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"What went wrong, in plain words.","examples":["Use POST with a JSON body. The full description is at https://heedeo.com/openapi.json."]}}}}}}}}},"/api/decide":{"get":{"operationId":"decideGet","summary":"Run the demo policy on a request","description":"Runs the real Heedeo engine (@heedeo/core, the same code the product's API runs) on the demo policy shown on heedeo.com (see GET /api/policy) and returns the verdict with the rule and line that decided it. No side effects, nothing stored, CORS open. The same input gives the same answer, except `counter.resets_at` and a pacing `retry_after`, which depend on the current time.","parameters":[{"name":"route","in":"query","required":true,"schema":{"type":"string"},"example":"/signup"},{"name":"client","in":"query","required":true,"schema":{"type":"string","enum":["human","agent"]},"example":"agent"},{"name":"signed","in":"query","schema":{"type":"boolean","default":false},"example":true},{"name":"operator","in":"query","schema":{"type":"string"},"example":"chatgpt.com"},{"name":"principal","in":"query","schema":{"type":"string"},"example":"maya"},{"name":"count","in":"query","schema":{"type":"integer","minimum":0},"example":2},{"name":"method","in":"query","schema":{"type":"string"},"example":"POST"},{"name":"detected","in":"query","schema":{"type":"boolean","default":false},"example":false},{"name":"last_over_at","in":"query","schema":{"type":"string","format":"date-time"},"example":"2026-10-02T11:40:00Z"},{"name":"last_over_ago","in":"query","schema":{"type":"integer","minimum":0},"example":1200},{"name":"challenge_passed","in":"query","schema":{"type":"boolean","default":false},"example":false}],"responses":{"200":{"description":"The verdict, the HTTP status the site would answer with, and the rule line that produced it. The endpoint itself always answers 200 for a valid call; `status` is the status the protected site would send. Never cached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"},"examples":{"verifiedUnderCap":{"summary":"Verified agent from a trusted operator, 2nd signup today","value":{"verdict":"allow","status":200,"reason":"Verified agent on /signup: allow. Signed by chatgpt.com, a trusted operator. This account is at 2/5 per day on /signup.","rule":{"path":"/signup","line":8,"text":"verified: \"allow\","},"retry_after":null,"counter":{"used":2,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":2},"class":"verified","route":"/signup","path":"/signup","principal":"maya","retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"unknownSignup":{"summary":"Unknown agent on /signup","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /signup: challenge. No valid signature from a trusted operator.","rule":{"path":"/signup","line":10,"text":"unknown: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"unknown","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"signedUntrusted":{"summary":"Valid signature from an operator not in trustedOperators","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /signup: challenge. The signature is valid, but agent.example-operator.com is not in trustedOperators, so the agent counts as unknown.","rule":{"path":"/signup","line":10,"text":"unknown: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"detected","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"verifiedNoPrincipal":{"summary":"Verified agent that names no principal","value":{"verdict":"challenge","status":401,"reason":"Verified agent with no principal, so the per-principal cap can't be counted. A passkey challenge makes that passkey the principal. Signed by chatgpt.com, a trusted operator.","rule":{"path":"/signup","line":9,"text":"noPrincipal: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"verified","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"overCapAllowed":{"summary":"Principal at 7 of 5, last over-cap signup more than an hour ago: overCap lets it through","value":{"verdict":"allow","status":200,"reason":"This account is at 7/5 per day on /signup, over the cap. overCap allows 5 more at most 1/hour; this is 2 of 5.","rule":{"path":"/signup","line":13,"text":"overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },"},"retry_after":null,"counter":{"used":7,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":7},"class":"verified","route":"/signup","path":"/signup","principal":"dev-7781","retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"throttled":{"summary":"Principal at 7 of 5, last over-cap signup 20 minutes ago: rate-limited","value":{"verdict":"throttle","status":429,"reason":"This account is at 7/5 per day on /signup, over the cap. overCap allows 5 more at most 1/hour, then blocks; the next one is due in 2400 seconds.","rule":{"path":"/signup","line":13,"text":"overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },"},"retry_after":2400,"counter":{"used":7,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":7},"class":"verified","route":"/signup","path":"/signup","principal":"dev-7781","retryAfter":2400,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"humanOverCap":{"summary":"A person at 12 of 5: the cap covers people too","value":{"verdict":"block","status":403,"reason":"This account is at 12/5 per day on /signup, past the cap and the 5 more overCap allows, so blocked.","rule":{"path":"/signup","line":13,"text":"overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },"},"retry_after":null,"counter":{"used":12,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":12},"class":"human","route":"/signup","path":"/signup","principal":"dave","retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"detectedDocs":{"summary":"Unsigned agent recognised by its user agent","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /signup: challenge. Recognised as an agent, but not verified.","rule":{"path":"/signup","line":10,"text":"unknown: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"detected","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"unknownCheckout":{"summary":"Unknown agent on /checkout","value":{"verdict":"block","status":403,"reason":"Unknown agent on /checkout: block. No valid signature from a trusted operator.","rule":{"path":"/checkout","line":15,"text":"\"/checkout\": { agents: { verified: \"allow\", unknown: \"block\" } },"},"retry_after":null,"counter":null,"class":"unknown","route":"/checkout","path":"/checkout","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"catchAll":{"summary":"Unknown agent on a route with no rule","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /pricing (no route rule, so the catch-all \"*\"): challenge. No valid signature from a trusted operator.","rule":{"path":"*","line":17,"text":"\"*\": { agents: { unknown: { challenge: \"passkey\" } } },"},"retry_after":null,"counter":null,"class":"unknown","route":"*","path":"/pricing","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}}}}}},"400":{"description":"Missing or invalid input. `error` says which field, `help` shows a valid call.","content":{"application/json":{"schema":{"type":"object","required":["ok","error","help"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","examples":["\"client\" is required and must be \"human\" or \"agent\"."]},"help":{"type":"string"}}}}}}}},"post":{"operationId":"decide","summary":"Run the demo policy on a request (JSON body)","description":"Same as GET, with the input as a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"},"examples":{"verified":{"value":{"route":"/signup","method":"POST","client":"agent","signed":true,"operator":"chatgpt.com","principal":"maya","count":2}},"unknown":{"value":{"route":"/checkout","client":"agent","signed":false}}}}}},"responses":{"200":{"description":"The verdict, the HTTP status the site would answer with, and the rule line that produced it. The endpoint itself always answers 200 for a valid call; `status` is the status the protected site would send. Never cached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"},"examples":{"verifiedUnderCap":{"summary":"Verified agent from a trusted operator, 2nd signup today","value":{"verdict":"allow","status":200,"reason":"Verified agent on /signup: allow. Signed by chatgpt.com, a trusted operator. This account is at 2/5 per day on /signup.","rule":{"path":"/signup","line":8,"text":"verified: \"allow\","},"retry_after":null,"counter":{"used":2,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":2},"class":"verified","route":"/signup","path":"/signup","principal":"maya","retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"unknownSignup":{"summary":"Unknown agent on /signup","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /signup: challenge. No valid signature from a trusted operator.","rule":{"path":"/signup","line":10,"text":"unknown: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"unknown","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"signedUntrusted":{"summary":"Valid signature from an operator not in trustedOperators","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /signup: challenge. The signature is valid, but agent.example-operator.com is not in trustedOperators, so the agent counts as unknown.","rule":{"path":"/signup","line":10,"text":"unknown: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"detected","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"verifiedNoPrincipal":{"summary":"Verified agent that names no principal","value":{"verdict":"challenge","status":401,"reason":"Verified agent with no principal, so the per-principal cap can't be counted. A passkey challenge makes that passkey the principal. Signed by chatgpt.com, a trusted operator.","rule":{"path":"/signup","line":9,"text":"noPrincipal: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"verified","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"overCapAllowed":{"summary":"Principal at 7 of 5, last over-cap signup more than an hour ago: overCap lets it through","value":{"verdict":"allow","status":200,"reason":"This account is at 7/5 per day on /signup, over the cap. overCap allows 5 more at most 1/hour; this is 2 of 5.","rule":{"path":"/signup","line":13,"text":"overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },"},"retry_after":null,"counter":{"used":7,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":7},"class":"verified","route":"/signup","path":"/signup","principal":"dev-7781","retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"throttled":{"summary":"Principal at 7 of 5, last over-cap signup 20 minutes ago: rate-limited","value":{"verdict":"throttle","status":429,"reason":"This account is at 7/5 per day on /signup, over the cap. overCap allows 5 more at most 1/hour, then blocks; the next one is due in 2400 seconds.","rule":{"path":"/signup","line":13,"text":"overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },"},"retry_after":2400,"counter":{"used":7,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":7},"class":"verified","route":"/signup","path":"/signup","principal":"dev-7781","retryAfter":2400,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"humanOverCap":{"summary":"A person at 12 of 5: the cap covers people too","value":{"verdict":"block","status":403,"reason":"This account is at 12/5 per day on /signup, past the cap and the 5 more overCap allows, so blocked.","rule":{"path":"/signup","line":13,"text":"overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },"},"retry_after":null,"counter":{"used":12,"limit":5,"window":"5/day","resets_at":"2026-10-03T00:00:00Z","attempts":12},"class":"human","route":"/signup","path":"/signup","principal":"dave","retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"detectedDocs":{"summary":"Unsigned agent recognised by its user agent","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /signup: challenge. Recognised as an agent, but not verified.","rule":{"path":"/signup","line":10,"text":"unknown: { challenge: \"passkey\" },"},"retry_after":null,"counter":null,"class":"detected","route":"/signup","path":"/signup","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"unknownCheckout":{"summary":"Unknown agent on /checkout","value":{"verdict":"block","status":403,"reason":"Unknown agent on /checkout: block. No valid signature from a trusted operator.","rule":{"path":"/checkout","line":15,"text":"\"/checkout\": { agents: { verified: \"allow\", unknown: \"block\" } },"},"retry_after":null,"counter":null,"class":"unknown","route":"/checkout","path":"/checkout","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}},"catchAll":{"summary":"Unknown agent on a route with no rule","value":{"verdict":"challenge","status":401,"reason":"Unknown agent on /pricing (no route rule, so the catch-all \"*\"): challenge. No valid signature from a trusted operator.","rule":{"path":"*","line":17,"text":"\"*\": { agents: { unknown: { challenge: \"passkey\" } } },"},"retry_after":null,"counter":null,"class":"unknown","route":"*","path":"/pricing","principal":null,"retryAfter":null,"policy":"demo","note":"The real Heedeo engine (@heedeo/core) on the demo policy shown on heedeo.com. Your own rules are set up during onboarding."}}}}}},"400":{"description":"Missing or invalid input. `error` says which field, `help` shows a valid call.","content":{"application/json":{"schema":{"type":"object","required":["ok","error","help"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","examples":["\"client\" is required and must be \"human\" or \"agent\"."]},"help":{"type":"string"}}}}}}}}},"/api/policy":{"get":{"operationId":"getPolicy","summary":"The demo policy, as source and as data","description":"Returns the policy source shown on heedeo.com verbatim (`source`, whose line numbers match `rule.line` from /api/decide) and the same rules as JSON (`rules`).","responses":{"200":{"description":"The demo policy.","content":{"application/json":{"schema":{"type":"object","required":["source","rules"],"properties":{"source":{"type":"string"},"rules":{"type":"object"}}},"example":{"source":"import { heedeo } from \"@heedeo/next\";\n\nexport default heedeo({\n  trustedOperators: [\"chatgpt.com\", \"browserbase.com\", \"anchorbrowser.io\"],\n  \"/signup\": {\n    humans: \"allow\",\n    agents: {\n      verified: \"allow\",\n      noPrincipal: { challenge: \"passkey\" },\n      unknown: { challenge: \"passkey\" },\n    },\n    perPrincipal: \"5/day\",\n    overCap: { throttle: 5, rate: \"1/hour\", then: \"block\" },\n  },\n  \"/checkout\": { agents: { verified: \"allow\", unknown: \"block\" } },\n  \"/docs/*\": { agents: \"allow\" },\n  \"*\": { agents: { unknown: { challenge: \"passkey\" } } },\n});","rules":{"trustedOperators":["chatgpt.com","browserbase.com","anchorbrowser.io"],"/signup":{"humans":"allow","agents":{"verified":"allow","noPrincipal":{"challenge":"passkey"},"unknown":{"challenge":"passkey"}},"perPrincipal":"5/day","overCap":{"throttle":5,"rate":"1/hour","then":"block"}},"/checkout":{"agents":{"verified":"allow","unknown":"block"}},"/docs/*":{"agents":"allow"},"*":{"agents":{"unknown":{"challenge":"passkey"}}}}}}}}}}},"/api/visitor":{"get":{"operationId":"getVisitor","summary":"How heedeo.com classifies this request","description":"A lightweight public classifier for heedeo.com itself. Returns a best guess at who is making the request from the user agent, plus a real Web Bot Auth check. If the request carries `Signature-Input`, `Signature` and `Signature-Agent`, the RFC 9421 signature is verified with Ed25519 against the keys the agent operator publishes at `<Signature-Agent origin>/.well-known/http-message-signatures-directory`, matched by JWK thumbprint (RFC 7638). `signed` only means the headers were present. `signature.valid` means the signature checks out and was not replayed. `verified` and `signature.verified` are true only when it is valid and the operator is in the policy's `trustedOperators` (chatgpt.com, browserbase.com, anchorbrowser.io, and their subdomains). A valid signature from any other operator is reported as signed, untrusted, and counts as an unknown agent. A signature that already verified is refused if sent again before it expires (`replayed signature`); that cache is in memory per Workers isolate, so it is best effort, not global.","responses":{"200":{"description":"The classification. Never cached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Visitor"},"examples":{"agent":{"summary":"An agent recognized by its user agent, not signed","value":{"kind":"agent","name":"ChatGPT","signed":false,"verified":false,"verifiedFor":null,"summary":"Not signed. Classified from the user agent only.","signature":{"present":false,"valid":false,"trusted":false,"verified":false,"agentOrigin":null,"keyId":null,"reason":"no signature headers"}}},"verified":{"summary":"A signed agent whose signature verified","value":{"kind":"agent","name":"ChatGPT agent","signed":true,"verified":true,"verifiedFor":"https://chatgpt.com","summary":"Verified agent for https://chatgpt.com: a trusted operator, and the Web Bot Auth signature matches a key in its published directory.","signature":{"present":true,"valid":true,"trusted":true,"verified":true,"agentOrigin":"https://chatgpt.com","keyId":"poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U","reason":"signature valid"}}},"signedUntrusted":{"summary":"A valid signature from an operator that is not trusted","value":{"kind":"agent","name":"http-message-signatures-example.research.cloudflare.com","signed":true,"verified":false,"verifiedFor":null,"summary":"Signed, untrusted: the signature from https://http-message-signatures-example.research.cloudflare.com is valid, but http-message-signatures-example.research.cloudflare.com is not a trusted operator, so it counts as an unknown agent.","signature":{"present":true,"valid":true,"trusted":false,"verified":false,"agentOrigin":"https://http-message-signatures-example.research.cloudflare.com","keyId":"poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U","reason":"signature valid, but http-message-signatures-example.research.cloudflare.com is not a trusted operator"}}},"badSignature":{"summary":"Signature headers present but they don't verify","value":{"kind":"agent","name":"script","signed":true,"verified":false,"verifiedFor":null,"summary":"Signature headers present but not verified (Signature-Input is not a valid structured field). Classified from the user agent only.","signature":{"present":true,"valid":false,"trusted":false,"verified":false,"agentOrigin":null,"keyId":null,"reason":"Signature-Input is not a valid structured field"}}},"human":{"value":{"kind":"human","name":null,"signed":false,"verified":false,"verifiedFor":null,"summary":"Not signed. Classified from the user agent only.","signature":{"present":false,"valid":false,"trusted":false,"verified":false,"agentOrigin":null,"keyId":null,"reason":"no signature headers"}}}}}}}}}}},"components":{"schemas":{"BookRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"description":"The email of the person who wants access. Stored in lowercase."},"site":{"type":["string","null"],"maxLength":200,"description":"Their site. Optional. Must be a string, or the API returns 400. Longer values are cut."},"pain":{"type":["string","null"],"maxLength":1000,"description":"What agents are doing on their site, so the call can start there. Optional. Must be a string, or the API returns 400. Longer values are cut."},"via":{"type":"string","enum":["human","agent"],"default":"human","description":"Use `agent` when you're requesting a call for someone."},"agent":{"type":["string","null"],"maxLength":80,"description":"The agent's name, for example `ChatGPT agent`. Must be a string, or the API returns 400. Longer values are cut."},"company":{"type":"string","description":"Leave this empty. It's a honeypot."}}},"BookResponse":{"type":"object","required":["ok","position","existing","status","message"],"properties":{"ok":{"type":"boolean","const":true},"position":{"type":["integer","null"],"deprecated":true,"description":"Legacy field. Still returned but no longer meaningful: ignore it. It may be an integer or null, so clients should treat null as normal."},"existing":{"type":"boolean","description":"True if this email had already requested a call."},"status":{"type":"string","enum":["confirmed","pending"],"description":"`confirmed` means the request counts. `pending` means it counts once the person confirms, by booking themselves or when the team checks with them."},"message":{"type":"string","description":"A sentence you can pass on to the person as is. On a repeat request it says where things stand."}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","description":"What went wrong, in plain words.","examples":["That email doesn't look right."]}}},"Visitor":{"type":"object","required":["kind","name","signed","verified","verifiedFor","summary","signature"],"properties":{"kind":{"type":"string","enum":["human","agent","crawler"],"description":"`agent` acts for a person. `crawler` indexes or trains."},"name":{"type":["string","null"],"description":"A readable name, for example `ChatGPT` or `GPTBot`. `script` for plain HTTP clients asking for markdown."},"signed":{"type":"boolean","description":"Web Bot Auth signature headers were present. See `verified` for whether they checked out."},"verified":{"type":"boolean","description":"The Web Bot Auth signature verified against the operator's published keys, was not a replay, and the operator is in `trustedOperators`. Never true otherwise."},"verifiedFor":{"type":["string","null"],"description":"The origin the agent is verified for, for example `https://chatgpt.com`. Null unless `verified`."},"summary":{"type":"string","description":"One sentence on how the request was classified."},"signature":{"$ref":"#/components/schemas/SignatureCheck"}}},"SignatureCheck":{"type":"object","required":["present","valid","trusted","verified","agentOrigin","keyId","reason"],"description":"Result of verifying the request's Web Bot Auth signature (HTTP Message Signatures, RFC 9421, Ed25519). The signature must cover `@authority` and `signature-agent`, carry `tag=\"web-bot-auth\"`, `created` and `expires` (60 seconds of clock skew allowed), and its `keyid` must be the RFC 7638 thumbprint of an Ed25519 key in the directory at `<Signature-Agent origin>/.well-known/http-message-signatures-directory`. Directories are fetched over https only, from public hostnames, with a 2 second timeout, and cached for 10 minutes.","properties":{"present":{"type":"boolean","description":"Any signature header was present."},"valid":{"type":"boolean","description":"The signature is valid and was not seen before (not a replay)."},"trusted":{"type":"boolean","description":"The operator in `Signature-Agent` is in the policy's `trustedOperators`, or a subdomain of one."},"verified":{"type":"boolean","description":"`valid` and `trusted`. Only then does the agent count as verified."},"agentOrigin":{"type":["string","null"],"description":"The origin from `Signature-Agent`.","examples":["https://chatgpt.com"]},"keyId":{"type":["string","null"],"description":"The `keyid` the signature names."},"reason":{"type":"string","description":"Why it did or didn't verify.","examples":["signature valid","signature valid, but example-operator.com is not a trusted operator","replayed signature","no signature headers","expired","key not found in directory","signature does not match"]}}},"DecideRequest":{"type":"object","required":["route","client"],"properties":{"route":{"type":"string","description":"The path being requested, starting with `/`. Normalized before matching: query and fragment dropped, percent escapes decoded, `\\` read as `/`, repeated slashes collapsed, `.` and `..` resolved, lowercased, trailing slash dropped. A path no route matches falls to the catch-all `*` rule.","examples":["/signup"]},"method":{"type":"string","enum":["GET","HEAD","POST","PUT","PATCH","DELETE","OPTIONS"],"description":"Optional. Not used by the demo rules."},"client":{"type":"string","enum":["human","agent"]},"signed":{"type":"boolean","default":false,"description":"The agent's Web Bot Auth signature is valid. Counts as verified only together with an `operator` in `trustedOperators`. Unsigned agents, and signed agents from other operators, are `unknown` in the rules."},"operator":{"type":["string","null"],"maxLength":253,"description":"The signing operator, the host of `Signature-Agent`, for example `chatgpt.com` or `https://chatgpt.com`. Trusted when it is in `trustedOperators` or a subdomain of one.","examples":["chatgpt.com"]},"principal":{"type":["string","null"],"maxLength":120,"description":"Who the request acts for, person or agent alike. The per-principal cap counts against it. Echoed back in the response, never put in `reason`.","examples":["maya"]},"detected":{"type":"boolean","default":false,"description":"An unsigned agent recognised by its user agent (for example Claude or GPTBot). Rules treat it as `unknown`; only the reason changes."},"count":{"type":"integer","minimum":0,"default":0,"description":"This request's position in the principal's current window on this route, counting itself (`perPrincipal`: N/min, N/hour, N/day, N/month or N/lifetime). Needs `principal`. 0 or omitted: not counted. On /signup the cap is 5 a day for people and agents alike. The 6th to 10th are allowed at most one an hour (`overCap`); one sooner than that is throttled (429, `retry_after` until the next is due, see `last_over_at`). From the 11th, blocked (403) until the day resets."},"last_over_at":{"type":"string","format":"date-time","description":"When this principal's last over-cap request was allowed, for the overCap pacing. Omitted: none in this window, so an over-cap request within the overCap allowance is allowed.","examples":["2026-10-02T11:40:00Z"]},"last_over_ago":{"type":"integer","minimum":0,"description":"`last_over_at` as seconds before now (1200 is 20 minutes ago). Send one or the other.","examples":[1200]},"challenge_passed":{"type":"boolean","default":false,"description":"The request carries a completed passkey challenge, which satisfies a `challenge` rule."}}},"Decision":{"type":"object","required":["verdict","status","reason","rule","retry_after","counter","class","route","path","principal","retryAfter","policy","note"],"properties":{"verdict":{"type":"string","enum":["allow","challenge","throttle","block"]},"status":{"type":"integer","enum":[200,401,429,403],"description":"The HTTP status the protected site would answer with: 200 allow, 401 challenge (passkey), 429 throttle (rate-limited, retry later), 403 block."},"retry_after":{"type":["integer","null"],"description":"Seconds before retrying, sent as `Retry-After`. Set only when `verdict` is `throttle`.","examples":[2400]},"retryAfter":{"type":["integer","null"],"deprecated":true,"description":"The old name of `retry_after`, same value."},"counter":{"type":["object","null"],"description":"The cap this request counts against, when it is counted: `used` (this request's position, the number the reason quotes), `limit`, `window`, `resets_at` (null for a lifetime window) and `attempts`.","properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"window":{"type":"string","examples":["5/day"]},"resets_at":{"type":["string","null"],"format":"date-time"},"attempts":{"type":"integer"}}},"class":{"type":"string","enum":["human","verified","detected","unknown"],"description":"How the request was classed. `detected` (recognised, or signed by an operator not in `trustedOperators`) is treated as `unknown` by the rules."},"route":{"type":"string","description":"The route key that matched (`*` for the catch-all)."},"path":{"type":"string","description":"The normalized path."},"reason":{"type":"string","description":"Why, in plain words. Never contains the principal."},"principal":{"type":["string","null"],"description":"Your own `principal` input, echoed back. Null when none was given."},"rule":{"type":"object","description":"The line that decided: its route path (`*` for the catch-all), the 1-based line in the policy source (GET /api/policy) and that line's text. Always set.","required":["path","line","text"],"properties":{"path":{"type":"string"},"line":{"type":"integer"},"text":{"type":"string"}}},"policy":{"type":"string","const":"demo"},"note":{"type":"string"}}}}}}