{"openapi":"3.1.0","info":{"title":"naulon API","version":"1.0.0","summary":"Price, settle and account for machine reads of your site.","description":"The public naulon control-plane API. Authenticate with an `nln_live_` key as a bearer token. Endpoints are tenant-scoped: a key can only read or settle for the site it is bound to.\n\nMoney is integer micro-USDC everywhere (`1_000_000` = $1). Any formatted decimal beside it is a convenience — never parse one back.\n\nThe prose guides at https://naulon.app/docs explain the contracts this document only types.","termsOfService":"https://naulon.app/terms","contact":{"name":"naulon support","email":"help@naulon.app","url":"https://naulon.app/docs"},"x-logo":{"url":"https://naulon.app/brand-kit/naulon-mark.svg","altText":"naulon","href":"https://naulon.app"}},"servers":[{"url":"https://gate.naulon.app","description":"The naulon fleet."}],"externalDocs":{"url":"https://naulon.app/docs","description":"The written guides — what to build, and why each contract is shaped as it is."},"tags":[{"name":"Enforce","description":"Price a resource and settle a payment for it. The path a publisher's own runtime calls when it enforces the toll itself rather than routing through the hosted gate."},{"name":"Licences","description":"Quote, buy and present a licence. A licence bought over a scope and period is access; the permanent citation record is what outlives it."},{"name":"Config","description":"What the site is and how it is configured, as the toll sees it."},{"name":"Earnings","description":"What was earned, what settled, and the exports built from it — statements, reconciliation, CSV and PDF."},{"name":"Audit","description":"What the toll observed per agent: paid, denied, served free."},{"name":"Members","description":"The author roster attached to a site."},{"name":"Agents","description":"For an agent with no naulon account: ask a question and get back a priced menu of licensed sources as an HTTP 402. No key. A fleet can run with this door off, and then it answers 404."},{"name":"Webhooks","description":"What naulon POSTs to you. Every signed delivery carries the same envelope; the event's own fields are under `data`."}],"components":{"securitySchemes":{"naulonKey":{"type":"http","scheme":"bearer","description":"An `nln_live_` publisher key."}},"schemas":{"SettlementLeg":{"type":"object","properties":{"role":{"type":"string","example":"author"},"payTo":{"type":"string","description":"The address this leg paid.","example":"0x1d2f..."},"microUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"settled":{"type":"boolean","example":true},"settlementRef":{"type":["string","null"],"description":"On-chain reference for THIS leg, or null when it genuinely could not be pinned to one settlement. Never faked.","example":"0xab12..."}},"required":["role","payTo","microUsdc","settled","settlementRef"]},"EnforcementStatusRow":{"type":"object","properties":{"host":{"type":"string"},"mode":{"type":["string","null"]},"confidence":{"type":["string","null"]},"basedOn":{"type":"array","items":{"type":"string"}},"lastCheckedAt":{"type":["string","null"]},"keyRejectedAt":{"type":["string","null"]},"nextAction":{"type":"string"},"attention":{"type":"boolean"},"recordToFix":{"type":"string"},"tracks":{"type":"object","additionalProperties":{"type":"string"}}},"required":["host","mode","confidence","basedOn","lastCheckedAt","keyRejectedAt","nextAction","attention","tracks"]},"LicenceQuote":{"type":"object","properties":{"priceMicro":{"type":"number","description":"What the AUTHORS receive, summed. Not what the buyer is charged."},"feeMicro":{"type":"number","description":"The naulon fee: a separate additive buyer→operator leg."},"buyerTotalMicro":{"type":"number","description":"priceMicro + feeMicro. What the buyer's balance is debited, and the only figure a buy control may carry."},"patterns":{"type":"array","items":{"type":"string"}},"terms":{"type":"array","items":{"type":"string"}},"period":{"type":"object","properties":{"from":{"type":"number"},"until":{"type":"number"}},"required":["from","until"]},"resourceCount":{"type":"number"},"legs":{"type":"array","items":{"type":"object","properties":{"toAddress":{"type":"string"},"amountMicro":{"type":"number"}},"required":["toAddress","amountMicro"]}}},"required":["priceMicro","feeMicro","buyerTotalMicro","patterns","terms","period","resourceCount","legs"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"HeldLicence":{"type":"object","properties":{"jti":{"type":"string"},"host":{"type":["string","null"],"description":"The site it was bought from — how a buyer tells two licences apart."},"patterns":{"type":"array","items":{"type":"string"},"description":"What the buyer asked for — the licence's name."},"grantedPatterns":{"type":"array","items":{"type":"string"},"description":"What it actually covers: one entry per page paid for."},"terms":{"type":"array","items":{"type":"string"}},"kind":{"type":"string"},"period":{"type":"object","properties":{"from":{"type":"number"},"until":{"type":"number"}},"required":["from","until"]},"priceMicro":{"type":"number","description":"What the AUTHORS received, summed."},"feeMicro":{"type":["number","null"],"description":"The naulon fee settled with it. Null on a sale recorded before the fee was stored."},"buyerTotalMicro":{"type":["number","null"],"description":"What the buyer was debited. Null exactly when feeMicro is."},"resourceCount":{"type":"number"},"legs":{"type":"array","items":{"type":"object","properties":{"toAddress":{"type":"string"},"amountMicro":{"type":"number"}},"required":["toAddress","amountMicro"]}},"settlementRef":{"type":["string","null"]},"settlementRefKind":{"type":"string","enum":["txHash","transferId","mock","none"],"description":"WHAT that reference is, decided here so no client re-derives it wrong. `mock` is test-mode output and must never be presented as a payment; only a `txHash` may be linked to an explorer."},"boughtAt":{"type":"number"}},"required":["jti","host","patterns","grantedPatterns","terms","kind","period","priceMicro","feeMicro","buyerTotalMicro","resourceCount","legs","settlementRef","settlementRefKind","boughtAt"]},"VerifyHostChallenge":{"type":"object","properties":{"host":{"type":"string"},"token":{"type":"string"},"method":{"type":"string"},"present":{},"verifiedAt":{"type":["string","null"]},"routingVerifiedAt":{"type":["string","null"]},"capability":{"type":"string","enum":["code","prefer_code","dns_only","locked","unknown"]},"codeArtifact":{"type":["string","null"],"enum":["npm","wordpress_plugin",null]}},"required":["host","token","method","verifiedAt","routingVerifiedAt","capability","codeArtifact"]},"VerifyHostAlreadyAdded":{"type":"object","properties":{"error":{"type":"string"},"routingVerified":{"type":"boolean"}},"required":["error","routingVerified"]},"VerifyHostOpenBody":{"type":"object","properties":{"host":{"type":"string","minLength":3,"maxLength":253,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i"},"method":{"type":"string","enum":["meta-tag","well-known","dns-txt"],"default":"well-known"}},"required":["host"]},"VerifyHostCheckBody":{"type":"object","properties":{"host":{"type":"string","minLength":3,"maxLength":253,"pattern":"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i"}},"required":["host"]},"PublisherTenants":{"type":"object","properties":{"tenants":{"type":"array","items":{"$ref":"#/components/schemas/TenantSelfRow"}},"chainsEnabled":{"type":"array","items":{"type":"string"}}},"required":["tenants","chainsEnabled"]},"TenantSelfRow":{"type":"object","properties":{"id":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"origin_url":{"type":["string","null"]},"article_prefixes":{"type":["array","null"],"items":{"type":"string"}},"price_usdc":{"type":"number"},"citation_multiplier":{"type":["number","null"]},"credits_api_url":{"type":["string","null"]},"credits_inline":{},"credits_free_slugs":{"type":["array","null"],"items":{"type":"string"}},"license_issuer":{"type":["string","null"]},"plan":{"type":["string","null"]},"status":{"type":"string"},"owner_user_id":{"type":["string","null"]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"directory_listed":{"type":"boolean"},"wallet_public":{"type":"boolean"},"showcase_listed":{"type":"boolean"},"proof_public":{"type":"boolean"}},"required":["id","hosts","origin_url","article_prefixes","price_usdc","citation_multiplier","credits_api_url","license_issuer","plan","status","owner_user_id","created_at","updated_at"]},"PlanGateError":{"type":"object","properties":{"error":{"type":"string"},"upgrade":{"type":"boolean","enum":[true]}},"required":["error","upgrade"]},"PublisherEarnings":{"type":"object","properties":{"generatedAt":{"type":"number"},"window":{"$ref":"#/components/schemas/Window"},"retentionClampedTo":{"type":"number"},"totals":{"$ref":"#/components/schemas/EarningsTotals"},"previous":{"type":"object","properties":{"totals":{"$ref":"#/components/schemas/EarningsTotals"}},"required":["totals"]},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/BreakdownRow"}},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/EarningsSite"}},"recent":{"type":"array","items":{"$ref":"#/components/schemas/Crossing"}},"nextCursor":{"type":"number"},"nextCursorId":{"type":"string"},"series":{"$ref":"#/components/schemas/EarningsSeries"},"payees":{"type":"array","items":{"type":"object","properties":{"wallet":{"type":"string"},"name":{"type":["string","null"]},"authorId":{"type":["string","null"]},"grossMicroUsdc":{"type":"number"},"events":{"type":"number"}},"required":["wallet","name","authorId","grossMicroUsdc","events"]},"description":"The window's money per payout address, biggest first. Sums to totals.grossMicroUsdc."}},"required":["generatedAt","window","totals","tenants","recent","series","payees"]},"Window":{"type":"object","properties":{"from":{"type":["number","null"]},"to":{"type":["number","null"]}},"required":["from","to"]},"EarningsTotals":{"type":"object","properties":{"tenants":{"type":"number"},"events":{"type":"number"},"reads":{"type":"number"},"citations":{"type":"number"},"grossMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"authors":{"type":"number"}},"required":["tenants","events","reads","citations","grossMicroUsdc","authors"]},"BreakdownRow":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"events":{"type":"number"},"reads":{"type":"number"},"citations":{"type":"number"},"grossMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["key","label","events","reads","citations","grossMicroUsdc"]},"EarningsSite":{"allOf":[{"$ref":"#/components/schemas/TenantLedger"},{"type":"object","properties":{"originUrl":{"type":["string","null"]}},"required":["originUrl"]}]},"TenantLedger":{"type":"object","properties":{"id":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"events":{"type":"number"},"reads":{"type":"number"},"citations":{"type":"number"},"grossMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"authors":{"type":"number"},"lastEventAt":{"type":["number","null"]}},"required":["id","hosts","events","reads","citations","grossMicroUsdc","authors","lastEventAt"]},"Crossing":{"type":"object","properties":{"host":{"type":"string"},"slug":{"type":"string"},"title":{"type":["string","null"],"description":"The page's catalog title, or null when the catalog has none."},"kind":{"type":"string","enum":["read","citation"]},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"at":{"type":"number"},"id":{"type":"string","description":"Ledger row id. Pages break `at` ties on it."},"payer":{"type":"string","description":"The wallet that paid."},"settlementRef":{"type":"string","description":"The settlement batch reference."},"payees":{"type":"array","items":{"type":"object","properties":{"authorId":{"type":"string"},"name":{"type":["string","null"]},"wallet":{"type":"string"},"share":{"type":"number"},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["authorId","name","wallet","share","micro"]},"description":"Each author's wallet, share and amount, split exactly as settled. `authorId` is the credits source's id, `name` the catalog byline for the wallet or null."}},"required":["host","slug","title","kind","micro","at","id","payer","settlementRef","payees"]},"EarningsSeries":{"type":"object","properties":{"unit":{"type":"string","enum":["hour","day","week"],"description":"Bucket width, chosen from the window's span: hourly up to 2 days, daily up to 120, weekly beyond. UTC."},"points":{"type":"array","items":{"type":"object","properties":{"at":{"type":"number"},"grossMicroUsdc":{"type":"number"},"reads":{"type":"number"},"citations":{"type":"number"}},"required":["at","grossMicroUsdc","reads","citations"]}}},"required":["unit","points"],"description":"Every crossing in the window, bucketed. Sums to `totals`."},"PublisherStatements":{"type":"object","properties":{"generatedAt":{"type":"number"},"window":{"$ref":"#/components/schemas/Window"},"retentionClampedTo":{"type":"number"},"statements":{"type":"array","items":{"$ref":"#/components/schemas/PayoutStatement"}},"totalMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"authors":{"type":"number"}},"required":["generatedAt","window","statements","totalMicroUsdc","authors"]},"PayoutStatement":{"type":"object","properties":{"wallet":{"type":"string"},"events":{"type":"number"},"reads":{"type":"number"},"citations":{"type":"number"},"grossMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PayoutStatementLine"}}},"required":["wallet","events","reads","citations","grossMicroUsdc","lines"]},"PayoutStatementLine":{"type":"object","properties":{"host":{"type":"string"},"slug":{"type":"string"},"kind":{"type":"string","enum":["read","citation"]},"share":{"type":"number","description":"This author's share of the crossing, 0..1."},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"at":{"type":"number"}},"required":["host","slug","kind","share","micro","at"]},"PublisherReconciliation":{"type":"object","properties":{"generatedAt":{"type":"number"},"window":{"$ref":"#/components/schemas/Window"},"retentionClampedTo":{"type":"number"},"recorded":{"type":"object","properties":{"events":{"type":"number"},"grossMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["events","grossMicroUsdc"]},"settled":{"$ref":"#/components/schemas/ReconciliationBucket"},"outstanding":{"$ref":"#/components/schemas/ReconciliationBucket"}},"required":["generatedAt","window","recorded","settled","outstanding"]},"ReconciliationBucket":{"type":"object","properties":{"legs":{"type":"number"},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["legs","micro"]},"PublisherAudit":{"type":"object","properties":{"generatedAt":{"type":"number"},"author":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"],"description":"Present when the read is filtered to one author: the byline the catalog writes them as."},"window":{"$ref":"#/components/schemas/Window"},"retentionClampedTo":{"type":"number"},"totals":{"$ref":"#/components/schemas/AuditTotals"},"previous":{"type":"object","properties":{"totals":{"$ref":"#/components/schemas/AuditTotals"}},"required":["totals"]},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/AuditBreakdownRow"}},"byAgent":{"type":"array","items":{"type":"object","properties":{"agent":{"type":"string"},"hits":{"type":"number"},"denied":{"type":"number"},"paid":{"type":"number"},"free":{"type":"number"},"blocked":{"type":"number"},"reread":{"type":"number"},"paymentFailed":{"type":"number"},"unservable":{"type":"number"},"masquerade":{"type":"number"},"operator":{"type":"string"},"purpose":{"type":"string"},"earnedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"missedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"firstAt":{"type":"number"},"lastAt":{"type":"number"},"verified":{"type":"boolean"}},"required":["agent","hits","denied","paid","free","blocked","reread","paymentFailed","unservable","masquerade","earnedMicroUsdc","missedMicroUsdc","firstAt","lastAt"]}},"byArticle":{"type":"array","items":{"$ref":"#/components/schemas/AuditArticleRow"}},"articleCount":{"type":"integer","description":"Articles in the window in all; `byArticle` carries the busiest of them."},"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"description":"The sites this read covers, for `site=`."},"heatmap":{"type":"object","properties":{"tzOffsetMinutes":{"type":"number"},"cells":{"type":"array","items":{"type":"array","items":{"type":"number"}}},"paid":{"type":"array","items":{"type":"array","items":{"type":"number"}}},"left":{"type":"array","items":{"type":"array","items":{"type":"number"}}}},"required":["tzOffsetMinutes","cells","paid","left"],"description":"Agent requests as cells[weekday][hour], Sunday = 0, shifted by `tz`."},"agentProfile":{"type":"object","properties":{"agent":{"type":"string"},"name":{"type":"string"},"operator":{"type":"string"},"purpose":{"type":"string"},"userAgents":{"type":"array","items":{"type":"object","properties":{"ua":{"type":"string"},"hits":{"type":"number"}},"required":["ua","hits"]}},"signedAs":{"type":"array","items":{"type":"string"}},"firstAt":{"type":"number"},"lastAt":{"type":"number"},"articles":{"type":"number"}},"required":["agent","userAgents","signedAs","firstAt","lastAt","articles"],"description":"Present when the read is filtered to one agent."},"operatorProfile":{"type":"object","properties":{"operator":{"type":"string"},"verified":{"type":"boolean","enum":[true]},"crawlers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"purpose":{"type":"string"},"hits":{"type":"number"},"verifiedHits":{"type":"number"}},"required":["name","hits","verifiedHits"]}},"userAgents":{"type":"array","items":{"type":"object","properties":{"ua":{"type":"string"},"hits":{"type":"number"}},"required":["ua","hits"]}},"signedAs":{"type":"array","items":{"type":"string"}},"forged":{"type":"number"},"masquerade":{"type":"number"},"sites":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string"},"host":{"type":"string"},"hits":{"type":"number"},"paid":{"type":"number"},"left":{"type":"number"},"free":{"type":"number"},"refused":{"type":"number"}},"required":["host","hits","paid","left","free","refused"]}},"agentTotal":{"type":"number","description":"Agent reads on the same view without the company filter."},"allTime":{"type":"object","properties":{"firstAt":{"type":"number"},"lastAt":{"type":"number"},"reads":{"type":"number"},"paid":{"type":"number"}},"required":["firstAt","lastAt","reads","paid"],"description":"The company over the plan's whole history."},"publishesAddresses":{"type":"boolean","description":"The company publishes its crawlers' addresses, so reads can be checked against them."},"armNeeded":{"type":"number","description":"Real reads a site must see before impostors of a crawler are charged."}},"required":["operator","crawlers","userAgents","signedAs","forged","masquerade","sites","agentTotal","allTime","publishesAddresses","armNeeded"],"description":"Present when the read is filtered to one company (`operator=`)."},"series":{"$ref":"#/components/schemas/AuditSeries"},"robots":{"type":"object","properties":{"checkedAt":{"type":"number"},"unreadHosts":{"type":"array","items":{"type":"string"}},"disallowed":{"type":"number"},"unknown":{"type":"number"},"byAgent":{"type":"array","items":{"type":"object","properties":{"agent":{"type":"string"},"disallowed":{"type":"number"},"unknown":{"type":"number"}},"required":["agent","disallowed","unknown"]}}},"required":["checkedAt","unreadHosts","disallowed","unknown","byAgent"],"description":"Agent requests held against each host's robots.txt as fetched at checkedAt (RFC 9309). `unknown` counts rows recorded before paths were, where the answer depends on the path."},"referrals":{"type":"object","properties":{"referredVisits":{"type":"number"},"byEngine":{"type":"array","items":{"type":"object","properties":{"operator":{"type":"string"},"visits":{"type":"number"},"agentRequests":{"type":"number"}},"required":["operator","visits","agentRequests"]}},"otherHosts":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"visits":{"type":"number"}},"required":["host","visits"]}}},"required":["referredVisits","byEngine","otherHosts"],"description":"People other sites sent (from the Referer host, host only), with each answer engine's visits beside its own agents' requests. Operators match the Company segment."},"identityArming":{"type":"array","items":{"type":"object","properties":{"tenantId":{"type":"string"},"operatorId":{"type":"string"},"label":{"type":"string"},"armed":{"type":"boolean"},"verifiedInWindow":{"type":"number"},"needed":{"type":"number"},"forgedServedFree":{"type":"number"}},"required":["tenantId","operatorId","label","armed","verifiedInWindow","needed","forgedServedFree"]},"description":"Per site and crawler: whether impostors are charged yet, and how far arming has come."},"recent":{"type":"array","items":{"$ref":"#/components/schemas/AuditObservation"}},"nextCursor":{"type":"number"},"nextCursorId":{"type":"string"},"truncated":{"type":"boolean"}},"required":["generatedAt","window","totals","byAgent","byArticle","articleCount","sites","heatmap","series","referrals","recent"]},"AuditTotals":{"type":"object","properties":{"observations":{"type":"number"},"agentHits":{"type":"number"},"denied":{"type":"number"},"paid":{"type":"number"},"servedFree":{"type":"number"},"paymentFailed":{"type":"number"},"missedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"failedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"failedByReason":{"type":"object","properties":{"insufficient_funds":{"type":"number"},"authorization_invalid":{"type":"number"},"malformed_payment":{"type":"number"},"network_unsupported":{"type":"number"},"settlement_failed":{"type":"number"}}},"earnedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"verifiedHits":{"type":"number"},"masqueradeAttempts":{"type":"number"},"forgedClaims":{"type":"number","description":"Requests that claimed a known crawler from an address outside its published ranges, over every row."},"forgedServedFree":{"type":"number","description":"Of those, how many read free."},"ipVerifiedClaims":{"type":"number","description":"Crawler claims from inside the crawler's published ranges."},"uncheckedClaims":{"type":"number","description":"Crawler claims that could not be checked."}},"required":["observations","agentHits","denied","paid","servedFree","paymentFailed","missedMicroUsdc","failedMicroUsdc","failedByReason","earnedMicroUsdc","verifiedHits","masqueradeAttempts","forgedClaims","forgedServedFree","ipVerifiedClaims","uncheckedClaims"]},"AuditBreakdownRow":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"hits":{"type":"number"},"denied":{"type":"number"},"paid":{"type":"number"},"missedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"earnedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["key","label","hits","denied","paid","missedMicroUsdc","earnedMicroUsdc"]},"AuditArticleRow":{"type":"object","properties":{"host":{"type":"string"},"slug":{"type":"string"},"path":{"type":"string"},"title":{"type":"string","description":"The catalog title, when the catalog has one."},"hits":{"type":"number"},"paid":{"type":"number"},"left":{"type":"number"},"free":{"type":"number"},"unpriced":{"type":"number","description":"Of free, reads of a page with no price at all."},"refused":{"type":"number"},"agents":{"type":"number"},"earnedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"missedMicroUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"lastAt":{"type":"number"}},"required":["host","slug","hits","paid","left","free","unpriced","refused","agents","earnedMicroUsdc","missedMicroUsdc","lastAt"],"description":"One article's agent traffic."},"AuditSeries":{"type":"object","properties":{"unit":{"type":"string","enum":["hour","day","week"],"description":"Bucket width, chosen from the window's span: hourly up to 2 days, daily up to 120, weekly beyond. UTC."},"points":{"type":"array","items":{"type":"object","properties":{"at":{"type":"number"},"paid":{"type":"number"},"left":{"type":"number"},"free":{"type":"number"},"refused":{"type":"number"},"earnedMicroUsdc":{"type":"number"},"missedMicroUsdc":{"type":"number"}},"required":["at","paid","left","free","refused","earnedMicroUsdc","missedMicroUsdc"]}}},"required":["unit","points"],"description":"Agent traffic over the window, bucketed by outcome. Humans excluded."},"AuditObservation":{"type":"object","properties":{"id":{"type":"string","description":"The observation's id. Pages break `at` ties on it."},"host":{"type":"string"},"slug":{"type":"string"},"path":{"type":"string","description":"Request path without its query string."},"kind":{"type":"string","enum":["read","citation"]},"verdict":{"type":"string","enum":["served-free","agent-reread","denied","blocked","payment-failed","unservable","paid"],"description":"The toll decision for this crossing."},"classifiedAs":{"type":"string","enum":["human","agent"]},"classifyReason":{"type":"string","description":"Why the classifier ruled human or agent."},"agentUa":{"type":"string","description":"Raw User-Agent (spoofable)."},"agent":{"type":"string","description":"The key this row buckets under in byAgent; what `agent=` takes."},"operator":{"type":"string","description":"The crawler registry's company for this caller."},"purpose":{"type":"string","description":"The crawler registry's purpose for this caller."},"verified":{"type":"boolean","description":"Web Bot Auth signature verified."},"verifiedAgent":{"type":"string","description":"Verified operator directory host."},"sigInvalid":{"type":"boolean","description":"A presented signature FAILED — masquerade."},"identityCheck":{"type":"string","enum":["signature","ip-verified","unverified","forged"],"description":"The crawler address check, when the user agent named a crawler."},"claimedOperator":{"type":"string","description":"The crawler the user agent claimed, e.g. google."},"forgedFrom":{"type":"string","description":"On a forged row only: the caller's network, a /24 or a /48."},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"failureReason":{"type":"string","description":"Why a payment-failed row failed (closed set)."},"referrerHost":{"type":"string","description":"Host of the page that sent a person here (human reads)."},"servedVia":{"type":"string","enum":["ingress"],"description":"Arrived through the crawler route."},"extraction":{"type":"string","enum":["gate","passthrough","raw"]},"servedBytes":{"type":"number"},"sourceBytes":{"type":"number"},"quotedAt":{"type":"number","description":"On a paid read that answered its own 402: when the quote was given."},"freeReason":{"type":"string","enum":["unpriced","terms","fleet","unavailable"],"description":"On an agent's free read: why nothing was charged."},"licenseJti":{"type":"string","description":"On a paid read: the licence it settled under. Check it at /verify?host=&jti=."},"at":{"type":"number"}},"required":["id","host","slug","verdict","classifiedAs","agent","at"]},"AuditRequestsPage":{"type":"object","properties":{"generatedAt":{"type":"number"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AuditObservation"}},"matched":{"type":"number","description":"Rows in the window matching the filter, before paging."},"nextCursor":{"type":"number"},"nextCursorId":{"type":"string"},"truncated":{"type":"boolean"}},"required":["generatedAt","rows","matched"]},"AuditTrace":{"type":"object","properties":{"observation":{"$ref":"#/components/schemas/AuditObservation"},"settlement":{"type":"object","properties":{"jti":{"type":"string","description":"The ledger row id, which is the licence jti."},"host":{"type":"string"},"at":{"type":"number"},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"payer":{"type":"string"},"payees":{"type":"array","items":{"type":"object","properties":{"authorId":{"type":"string"},"wallet":{"type":"string"},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["authorId","wallet","micro"]}},"forgone":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"payTo":{"type":"string"},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["role","payTo","micro"]}},"chainId":{"type":"number"},"scheme":{"type":"string","enum":["eip3009"]},"verifyingContract":{"type":"string"},"settlementRef":{"type":"string"},"terms":{"type":"object","properties":{"url":{"type":"string"},"sha256":{"type":"string"}},"required":["url","sha256"]},"title":{"type":"string"}},"required":["jti","host","at","micro","payer","payees","settlementRef"],"description":"For a paid read: the ledger row its payment settled as."},"join":{"type":"string","enum":["stamped","time"],"description":"stamped: named by the read. time: matched on an older row by site, article, amount and time."}},"required":["observation"]},"MembersRoster":{"type":"object","properties":{"org":{"type":["string","null"]},"authors":{"type":"array","items":{"$ref":"#/components/schemas/AuthorMember"}}},"required":["org","authors"]},"AuthorMember":{"type":"object","properties":{"tenantId":{"type":"string"},"authorId":{"type":"string"},"email":{"type":"string"},"userId":{"type":["string","null"]},"accepted":{"type":"boolean"},"inviteToken":{"type":["string","null"]}},"required":["tenantId","authorId","email","userId","accepted","inviteToken"]},"X402NoMatch":{"type":"object","properties":{"requestId":{"type":["string","null"],"description":"Null when nothing about the question was stored."},"eraseToken":{"type":"string","description":"Spend once at `POST /_naulon/x402/forget` to erase this question."},"privacy":{"type":"string","description":"What is kept, for how long, and how to erase it."},"question":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/X402MenuRow"}},"totalUsdc":{"type":"number","enum":[0]},"next":{"type":"string"}},"required":["requestId","privacy","question","sources","totalUsdc","next"]},"X402MenuRow":{"type":"object","properties":{"key":{"type":"string","description":"`site/slug`. What `recommended.picks` and `skipped` name."},"site":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"url":{"type":"string","description":"The page. A person reads it free."},"priceUsdc":{"type":"number","description":"What this caller pays, all in. 0 for a site that is observing."},"observing":{"type":"boolean","enum":[true],"description":"The site observes: the read is free, and `listPriceUsdc` is what it would charge."},"listPriceUsdc":{"type":"number"},"feeUsdc":{"type":"number","description":"The part of `priceUsdc` that is the operator's fee."},"network":{"type":"string","description":"Where this source settles, e.g. `arc`."},"fit":{"type":"string","enum":["direct","partial","none"]},"value":{"type":"string","enum":["high","medium","low"]},"stance":{"type":"string","enum":["new","deeper","overlaps","off_topic"]},"evidence":{"type":"object","properties":{"answering":{"type":"integer"},"checked":{"type":"integer"}},"required":["answering","checked"],"description":"Of the passages checked, how many answer the question directly."}},"required":["key","site","slug","title","summary","priceUsdc"]},"X402Quote":{"type":"object","properties":{"requestId":{"type":["string","null"],"description":"Null when nothing about the question was stored."},"eraseToken":{"type":"string","description":"Spend once at `POST /_naulon/x402/forget` to erase this question."},"privacy":{"type":"string","description":"What is kept, for how long, and how to erase it."},"x402Version":{"type":"number","enum":[2]},"error":{"type":"string","enum":["payment_required"]},"accepts":{"type":"array","items":{},"description":"Empty until payment at this door opens."},"question":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/X402MenuRow"}},"totalUsdc":{"type":"number"},"rule":{"$ref":"#/components/schemas/BuyRule"},"recommended":{"type":"object","properties":{"picks":{"type":"array","items":{"type":"string"}},"plane":{"type":["string","null"],"enum":["test","live",null]},"budgetUsdc":{"type":"number"}},"required":["picks","plane","budgetUsdc"]},"skipped":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string","enum":["not_judged","fit","evidence","price","stance","not_picked"]}},"required":["key","reason"]},"description":"Every source not recommended, with the part of the rule it missed, or `not_picked`."},"quote":{"type":"string","description":"Signed quote. Pass it to `POST /_naulon/v1/ask` to buy."},"quoteExpiresAt":{"type":"integer"},"next":{"type":"string"}},"required":["requestId","privacy","x402Version","error","accepts","question","sources","totalUsdc","skipped","next"]},"BuyRule":{"type":"object","properties":{"minFit":{"type":"string","enum":["direct","partial"],"description":"The weakest fit worth buying."},"minEvidence":{"type":"integer","minimum":0,"description":"Passages that must hold a direct answer."},"maxPerSourceUsdc":{"type":"number","minimum":0,"description":"The most one source may cost, all in."},"exclude":{"type":"array","items":{"type":"string","enum":["new","deeper","overlaps","off_topic"]},"description":"Stances never worth paying for."}},"description":"Echoed when the request carried one."}},"parameters":{}},"paths":{"/_naulon/enforce-config":{"get":{"summary":"The enforcement config for a resource's publisher","tags":["Enforce"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"resource","in":"query"}],"responses":{"200":{"description":"The config.","content":{"application/json":{"schema":{"type":"object","properties":{"enforcement":{"type":"object","properties":{},"additionalProperties":{}}},"required":["enforcement"],"additionalProperties":{}}}}},"400":{"description":"Missing or invalid resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Resource not owned by this key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/enforce-status":{"get":{"summary":"Per-host enforcement report for this key's tenant","tags":["Enforce"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"resource","in":"query"}],"responses":{"200":{"description":"The key works.","content":{"application/json":{"schema":{"type":"object","properties":{"hosts":{"type":"array","items":{"$ref":"#/components/schemas/EnforcementStatusRow"}},"attention":{"type":"boolean"},"selfHosted":{"type":"boolean"}},"required":["hosts","attention","selfHosted"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"The key does not serve this site.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/quote":{"get":{"summary":"Price one resource","tags":["Enforce"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"resource","in":"query"},{"schema":{"type":"string"},"required":false,"name":"slug","in":"query"},{"schema":{"type":"string","enum":["read","citation"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string"},"required":false,"name":"verifiedAgent","in":"query"},{"schema":{"type":"string"},"required":false,"name":"build","in":"query"},{"schema":{"type":"string"},"required":false,"name":"observe","in":"query"}],"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"type":"object","properties":{"price":{"type":"integer","minimum":0},"extraLegs":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"payTo":{"type":"string"},"amount":{"type":"string"}},"required":["role","payTo","amount"]}}},"required":["price"],"additionalProperties":{}}}}},"204":{"description":"No toll: a free read."},"400":{"description":"Missing or invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Resource not owned by this key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/verify":{"post":{"summary":"Settle a relayed payment","tags":["Enforce"],"security":[{"naulonKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"payment":{"type":"string","minLength":1},"legs":{"type":"array","items":{}},"quote":{},"resource":{"type":"string"},"agent":{"type":"object","properties":{"ua":{"type":"string"},"classifyReason":{"type":"string"},"verified":{"type":"boolean"},"verifiedAgent":{"type":"string"},"sigInvalid":{"type":"boolean"}}}}}}}},"responses":{"200":{"description":"Settled: serve the resource.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"verdict":{"type":"string","enum":["paid"]},"settlementRef":{"type":"string"},"payer":{"type":"string"},"responseHeader":{"type":"string"},"licenseJws":{"type":"string"},"chargedMicro":{"type":"string"}},"required":["ok","verdict"]}}}},"400":{"description":"Malformed body, quote or legs.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"verdict":{"type":"string","enum":["paid","refused","pending","unavailable"]},"error":{"type":"string"}},"required":["ok","error"]}}}},"401":{"description":"Missing or invalid key. No verdict; a runtime reads a 4xx without one as refused.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"verdict":{"type":"string","enum":["paid","refused","pending","unavailable"]},"error":{"type":"string"}},"required":["ok","error"]}}}},"402":{"description":"Not settled, or the site is observing (`verdict: refused`).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"verdict":{"type":"string","enum":["paid","refused","pending","unavailable"]},"error":{"type":"string"}},"required":["ok","error"]}}}},"403":{"description":"Suspended (`verdict: refused`), or the resource is not this key's (no verdict, read as refused).","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"verdict":{"type":"string","enum":["paid","refused","pending","unavailable"]},"error":{"type":"string"}},"required":["ok","error"]}}}},"503":{"description":"The payment rail could not be asked (`payment_rail_unavailable`, `verdict: unavailable`). Nothing was broadcast: serve the page.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"verdict":{"type":"string","enum":["paid","refused","pending","unavailable"]},"error":{"type":"string"}},"required":["ok","error"]}}}}}}},"/_naulon/license/check":{"post":{"summary":"Does this licence entitle a free re-read?","tags":["Enforce"],"security":[{"naulonKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"license":{"type":"string","minLength":1},"resource":{"type":"string"},"slug":{"type":"string","minLength":1},"kind":{"type":"string","enum":["read","citation"]},"proof":{"type":"string"}}}}}},"responses":{"200":{"description":"The verdict.","content":{"application/json":{"schema":{"type":"object","properties":{"entitled":{"type":"boolean"},"verdict":{"type":"string","enum":["paid","refused"]},"reason":{"type":"string","enum":["no_verifier"]}},"required":["entitled","verdict"]}}}},"400":{"description":"Bad request (`verdict: refused`).","content":{"application/json":{"schema":{"type":"object","properties":{"entitled":{"type":"boolean"},"verdict":{"type":"string","enum":["paid","refused"]},"reason":{"type":"string","enum":["no_verifier"]}},"required":["entitled","verdict"]}}}},"401":{"description":"Missing or invalid key. No verdict; a runtime reads a 4xx without one as refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Resource not owned by this key. No verdict; read as refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/observe":{"post":{"summary":"Report gating decisions","tags":["Enforce"],"security":[{"naulonKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"slug":{"type":"string"},"verdict":{"type":"string","enum":["served-free","agent-reread","denied","blocked","paid","payment-failed","unservable"]},"classifiedAs":{"type":"string","enum":["human","agent"]},"kind":{"type":"string","enum":["read","citation"]},"priceMicro":{"type":"integer","minimum":0},"at":{"type":"integer","exclusiveMinimum":0},"agent":{"type":"object","properties":{"ua":{"type":"string"},"classifyReason":{"type":"string"},"verified":{"type":"boolean"},"verifiedAgent":{"type":"string"},"sigInvalid":{"type":"boolean"}}},"referrerHost":{"type":"string","maxLength":253,"pattern":"^[a-z0-9.-]+$/i"},"identityCheck":{"type":"string","enum":["signature","ip-verified","unverified","forged"]},"claimedOperator":{"type":"string","maxLength":64},"observeOnly":{"type":"boolean"},"crawlerBudget":{"type":"string","maxLength":16},"paymentPresented":{"type":"boolean"},"freeReason":{"type":"string","maxLength":16},"forgedFrom":{"type":"string","maxLength":64}},"required":["resource","verdict","classifiedAs"]},{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string","format":"uri"},"slug":{"type":"string"},"verdict":{"type":"string","enum":["served-free","agent-reread","denied","blocked","paid","payment-failed","unservable"]},"classifiedAs":{"type":"string","enum":["human","agent"]},"kind":{"type":"string","enum":["read","citation"]},"priceMicro":{"type":"integer","minimum":0},"at":{"type":"integer","exclusiveMinimum":0},"agent":{"type":"object","properties":{"ua":{"type":"string"},"classifyReason":{"type":"string"},"verified":{"type":"boolean"},"verifiedAgent":{"type":"string"},"sigInvalid":{"type":"boolean"}}},"referrerHost":{"type":"string","maxLength":253,"pattern":"^[a-z0-9.-]+$/i"},"identityCheck":{"type":"string","enum":["signature","ip-verified","unverified","forged"]},"claimedOperator":{"type":"string","maxLength":64},"observeOnly":{"type":"boolean"},"crawlerBudget":{"type":"string","maxLength":16},"paymentPresented":{"type":"boolean"},"freeReason":{"type":"string","maxLength":16},"forgedFrom":{"type":"string","maxLength":64}},"required":["resource","verdict","classifiedAs"]},"minItems":1,"maxItems":50}]}}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"accepted":{"type":"integer"}},"required":["ok","accepted"]}}}},"400":{"description":"A money verdict, or a malformed report.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["ok","error"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["ok","error"]}}}},"403":{"description":"A host not owned by this key.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["ok","error"]}}}}}}},"/_naulon/licenses/quote":{"post":{"summary":"Price a licence over a scope","description":"What a licence covering these paths, for these terms, over this period would cost. Public: pricing needs no account. `404` means the scope covers nothing on this site.","tags":["Licences"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"array","items":{"type":"string"},"example":["/essays/*"]},"terms":{"type":"array","items":{"type":"string"},"example":["ai-input"]},"periodDays":{"type":"number","example":30},"kind":{"type":"string","enum":["read","citation"]}},"additionalProperties":{}}}}},"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenceQuote"}}}},"400":{"description":"Malformed scope, terms or period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope licences are not on sale on this fleet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such site, or the scope covers nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"This site cannot be sold as a scope — see `error`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/_naulon/licenses/held":{"get":{"summary":"The licences this account holds","description":"Every licence this account has bought on this site, newest first. Scoped to the caller: there is no parameter that widens it.","tags":["Licences"],"security":[{"nlnAgent":[]}],"responses":{"200":{"description":"The account's licences.","content":{"application/json":{"schema":{"type":"object","properties":{"licences":{"type":"array","items":{"$ref":"#/components/schemas/HeldLicence"}},"sellable":{"type":"boolean","description":"Whether this fleet is currently selling scope licences."}},"required":["licences","sellable"]}}}},"401":{"description":"Authenticate first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/_naulon/licenses/{jti}/access":{"post":{"summary":"Get a fresh access token for a licence you hold","description":"A Citation License Token is capped at minutes because it is an unrevocable bearer credential, so a 30-day licence cannot BE a 30-day token. While the purchased period is live this mints a fresh short token over the pages the licence covers. Pass `paths` to narrow it to what you are about to read.","tags":["Licences"],"security":[{"nlnAgent":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"jti","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"paths":{"type":"array","items":{"type":"string"},"example":["/essays/a"]}},"additionalProperties":{}}}}},"responses":{"200":{"description":"A short-lived licence covering the requested pages.","content":{"application/json":{"schema":{"type":"object","properties":{"license":{"type":"string"},"patterns":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"number"},"periodUntil":{"type":"number"}},"required":["license","patterns","expiresAt","periodUntil"]}}}},"401":{"description":"Authenticate first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The purchased period is over, or has not begun.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such licence for this account on this site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The paths asked for are outside the licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"This deployment cannot mint right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/_naulon/licenses":{"post":{"summary":"Buy a licence over a scope","description":"Without an `X-PAYMENT` header this answers `402` carrying the offer, exactly as a toll does. With one, it settles the payment buyer→author, mints the licence and returns it.","tags":["Licences"],"security":[{"nlnAgent":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"array","items":{"type":"string"},"example":["/essays/*"]},"terms":{"type":"array","items":{"type":"string"},"example":["ai-input"]},"periodDays":{"type":"number","example":30},"kind":{"type":"string","enum":["read","citation"]}},"additionalProperties":{}}}}},"responses":{"200":{"description":"Bought. The licence is a signed JWS; verify it against the published JWKS.","content":{"application/json":{"schema":{"type":"object","properties":{"license":{"type":"string"},"jti":{"type":["string","null"]},"priceMicro":{"type":"number"}},"required":["license","jti","priceMicro"]}}}},"401":{"description":"A licence is issued to an account; authenticate first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (the offer), or the payment was refused/incomplete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope licences are not on sale on this fleet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/_naulon/verify-host":{"post":{"summary":"Open a host-ownership challenge","description":"Opens (or returns) the ownership challenge for a host on the key's own tenant, and returns what to serve. Idempotent per host. `cname` is not offered here — it is the fleet routing proof, and fleet routing plus in-app enforcement double-tolls.","tags":["Enforce"],"security":[{"naulonKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyHostOpenBody"}}}},"responses":{"201":{"description":"The challenge to serve.","content":{"application/json":{"schema":{"type":"object","properties":{"challenge":{"$ref":"#/components/schemas/VerifyHostChallenge"}},"required":["challenge"]}}}},"400":{"description":"Bad request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Host is already verified on this site. `routingVerified: true` means it is fleet-routed and already being tolled — do NOT turn in-app enforcement on, that double-tolls the agent. Remove the fleet CNAME first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyHostAlreadyAdded"}}}}}},"get":{"summary":"List this tenant's host challenges","tags":["Enforce"],"security":[{"naulonKey":[]}],"responses":{"200":{"description":"Challenges.","content":{"application/json":{"schema":{"type":"object","properties":{"challenges":{"type":"array","items":{"$ref":"#/components/schemas/VerifyHostChallenge"}}},"required":["challenges"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/verify-host/check":{"post":{"summary":"Check a host-ownership challenge","description":"Asks the control plane to fetch the challenge and stamp ownership. 200 = verified (the host can now settle in-app); 409 = not yet, with a reason. Never promotes the host into fleet routing.","tags":["Enforce"],"security":[{"naulonKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyHostCheckBody"}}}},"responses":{"200":{"description":"Ownership proven.","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean","enum":[true]},"host":{"type":"string"}},"required":["verified","host"]}}}},"400":{"description":"Bad request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Not verified yet — the reason a setup wizard diagnoses against.","content":{"application/json":{"schema":{"type":"object","properties":{"verified":{"type":"boolean","enum":[false]},"reason":{"type":"string"}},"required":["verified","reason"]}}}}}}},"/_naulon/tenants/self":{"get":{"summary":"The key's own tenant config","tags":["Config"],"security":[{"naulonKey":[]}],"responses":{"200":{"description":"The bound tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherTenants"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/earnings":{"get":{"summary":"Earnings rollup","tags":["Earnings"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string","enum":["read","citation"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","description":"One page."},"required":false,"description":"One page.","name":"slug","in":"query"},{"schema":{"type":"string","description":"One payout wallet, case-insensitive. Figures become that author's cut; rows stay whole crossings."},"required":false,"description":"One payout wallet, case-insensitive. Figures become that author's cut; rows stay whole crossings.","name":"author","in":"query"}],"responses":{"200":{"description":"The earnings snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherEarnings"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/earnings/statements":{"get":{"summary":"Payout statements","tags":["Earnings"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Per-author payout statements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherStatements"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/earnings/reconciliation":{"get":{"summary":"Settlement reconciliation","tags":["Earnings"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Recorded vs settled vs outstanding.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherReconciliation"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/earnings/export.csv":{"get":{"summary":"Earnings CSV export","tags":["Earnings"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string","enum":["read","citation"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","description":"One page."},"required":false,"description":"One page.","name":"slug","in":"query"},{"schema":{"type":"string","description":"One payout wallet, case-insensitive. Figures become that author's cut; rows stay whole crossings."},"required":false,"description":"One payout wallet, case-insensitive. Figures become that author's cut; rows stay whole crossings.","name":"author","in":"query"}],"responses":{"200":{"description":"CSV export.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/earnings/export.pdf":{"get":{"summary":"Earnings PDF export","tags":["Earnings"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"PDF export.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/audit":{"get":{"summary":"Agent traffic audit","tags":["Audit"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"One outcome, or several comma-separated."},"required":false,"description":"One outcome, or several comma-separated.","name":"verdict","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agent","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string"},"required":false,"name":"slug","in":"query"},{"schema":{"type":"string","description":"Crawler registry company (`Unrecognised` for the rest)."},"required":false,"description":"Crawler registry company (`Unrecognised` for the rest).","name":"operator","in":"query"},{"schema":{"type":"string","description":"Crawler registry purpose (`unknown` for the rest)."},"required":false,"description":"Crawler registry purpose (`unknown` for the rest).","name":"purpose","in":"query"},{"schema":{"type":"string","enum":["verified","unsigned","masquerade","forged","ip-verified","not-checked"]},"required":false,"name":"identity","in":"query"},{"schema":{"type":"string","description":"Case-insensitive search over path, article, site, agent and referrer."},"required":false,"description":"Case-insensitive search over path, article, site, agent and referrer.","name":"q","in":"query"},{"schema":{"type":"string","description":"One author, by canonical author id: the pages the catalog credits to them. 503 when the catalog cannot be read."},"required":false,"description":"One author, by canonical author id: the pages the catalog credits to them. 503 when the catalog cannot be read.","name":"author","in":"query"},{"schema":{"type":"string","enum":["read","citation"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","enum":["agent","human","all"],"description":"Whose requests the list holds. Default agent."},"required":false,"description":"Whose requests the list holds. Default agent.","name":"who","in":"query"},{"schema":{"type":"string","description":"Minutes east of UTC for the heatmap and the weekday/hour filter. Default 0."},"required":false,"description":"Minutes east of UTC for the heatmap and the weekday/hour filter. Default 0.","name":"tz","in":"query"},{"schema":{"type":"string","description":"One heatmap row: 0 (Sunday) to 6."},"required":false,"description":"One heatmap row: 0 (Sunday) to 6.","name":"weekday","in":"query"},{"schema":{"type":"string","description":"One heatmap column: 0 to 23."},"required":false,"description":"One heatmap column: 0 to 23.","name":"hour","in":"query"}],"responses":{"200":{"description":"The audit snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublisherAudit"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/audit/requests":{"get":{"summary":"One page of agent requests","tags":["Audit"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"One outcome, or several comma-separated."},"required":false,"description":"One outcome, or several comma-separated.","name":"verdict","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agent","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string"},"required":false,"name":"slug","in":"query"},{"schema":{"type":"string","description":"Crawler registry company (`Unrecognised` for the rest)."},"required":false,"description":"Crawler registry company (`Unrecognised` for the rest).","name":"operator","in":"query"},{"schema":{"type":"string","description":"Crawler registry purpose (`unknown` for the rest)."},"required":false,"description":"Crawler registry purpose (`unknown` for the rest).","name":"purpose","in":"query"},{"schema":{"type":"string","enum":["verified","unsigned","masquerade","forged","ip-verified","not-checked"]},"required":false,"name":"identity","in":"query"},{"schema":{"type":"string","description":"Case-insensitive search over path, article, site, agent and referrer."},"required":false,"description":"Case-insensitive search over path, article, site, agent and referrer.","name":"q","in":"query"},{"schema":{"type":"string","description":"One author, by canonical author id: the pages the catalog credits to them. 503 when the catalog cannot be read."},"required":false,"description":"One author, by canonical author id: the pages the catalog credits to them. 503 when the catalog cannot be read.","name":"author","in":"query"},{"schema":{"type":"string","enum":["read","citation"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","enum":["agent","human","all"],"description":"Whose requests the list holds. Default agent."},"required":false,"description":"Whose requests the list holds. Default agent.","name":"who","in":"query"},{"schema":{"type":"string","description":"Minutes east of UTC for the heatmap and the weekday/hour filter. Default 0."},"required":false,"description":"Minutes east of UTC for the heatmap and the weekday/hour filter. Default 0.","name":"tz","in":"query"},{"schema":{"type":"string","description":"One heatmap row: 0 (Sunday) to 6."},"required":false,"description":"One heatmap row: 0 (Sunday) to 6.","name":"weekday","in":"query"},{"schema":{"type":"string","description":"One heatmap column: 0 to 23."},"required":false,"description":"One heatmap column: 0 to 23.","name":"hour","in":"query"}],"responses":{"200":{"description":"A page of the filtered requests, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRequestsPage"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/audit/requests/{id}/trace":{"get":{"summary":"One request in full, with the proof behind a paid read","tags":["Audit"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The request and, when paid, its settlement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditTrace"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}},"404":{"description":"No such request among your sites."}}}},"/_naulon/audit/export.csv":{"get":{"summary":"Audit CSV export","tags":["Audit"],"security":[{"naulonKey":[]}],"parameters":[{"schema":{"type":"string","description":"Window start, epoch ms."},"required":false,"description":"Window start, epoch ms.","name":"from","in":"query"},{"schema":{"type":"string","description":"Window end, epoch ms."},"required":false,"description":"Window end, epoch ms.","name":"to","in":"query"},{"schema":{"type":"string","enum":["0","1"],"description":"Also compute the prior window."},"required":false,"description":"Also compute the prior window.","name":"compare","in":"query"},{"schema":{"type":"string","description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict."},"required":false,"description":"Segmentation key. Earnings: host, slug, author, kind. Audit: agent, operator, purpose, host, slug, verdict.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Paging cursor (epoch ms)."},"required":false,"description":"Paging cursor (epoch ms).","name":"cursor","in":"query"},{"schema":{"type":"string","description":"The id half of the cursor, so rows sharing a millisecond page cleanly."},"required":false,"description":"The id half of the cursor, so rows sharing a millisecond page cleanly.","name":"cursorId","in":"query"},{"schema":{"type":"string"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"One outcome, or several comma-separated."},"required":false,"description":"One outcome, or several comma-separated.","name":"verdict","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agent","in":"query"},{"schema":{"type":"string"},"required":false,"name":"host","in":"query"},{"schema":{"type":"string"},"required":false,"name":"slug","in":"query"},{"schema":{"type":"string","description":"Crawler registry company (`Unrecognised` for the rest)."},"required":false,"description":"Crawler registry company (`Unrecognised` for the rest).","name":"operator","in":"query"},{"schema":{"type":"string","description":"Crawler registry purpose (`unknown` for the rest)."},"required":false,"description":"Crawler registry purpose (`unknown` for the rest).","name":"purpose","in":"query"},{"schema":{"type":"string","enum":["verified","unsigned","masquerade","forged","ip-verified","not-checked"]},"required":false,"name":"identity","in":"query"},{"schema":{"type":"string","description":"Case-insensitive search over path, article, site, agent and referrer."},"required":false,"description":"Case-insensitive search over path, article, site, agent and referrer.","name":"q","in":"query"},{"schema":{"type":"string","description":"One author, by canonical author id: the pages the catalog credits to them. 503 when the catalog cannot be read."},"required":false,"description":"One author, by canonical author id: the pages the catalog credits to them. 503 when the catalog cannot be read.","name":"author","in":"query"},{"schema":{"type":"string","enum":["read","citation"]},"required":false,"name":"kind","in":"query"},{"schema":{"type":"string","enum":["agent","human","all"],"description":"Whose requests the list holds. Default agent."},"required":false,"description":"Whose requests the list holds. Default agent.","name":"who","in":"query"},{"schema":{"type":"string","description":"Minutes east of UTC for the heatmap and the weekday/hour filter. Default 0."},"required":false,"description":"Minutes east of UTC for the heatmap and the weekday/hour filter. Default 0.","name":"tz","in":"query"},{"schema":{"type":"string","description":"One heatmap row: 0 (Sunday) to 6."},"required":false,"description":"One heatmap row: 0 (Sunday) to 6.","name":"weekday","in":"query"},{"schema":{"type":"string","description":"One heatmap column: 0 to 23."},"required":false,"description":"One heatmap column: 0 to 23.","name":"hour","in":"query"}],"responses":{"200":{"description":"Every filtered request in the window, newest first.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/members":{"get":{"summary":"Author/payee roster","tags":["Members"],"security":[{"naulonKey":[]}],"responses":{"200":{"description":"The org's author roster.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembersRoster"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API access not in the tenant's plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGateError"}}}}}}},"/_naulon/x402/ask":{"post":{"summary":"Ask a question, get a priced menu","description":"Surveys the licensed catalogue for the question and answers with an HTTP 402 menu: each source with its price, how well it fits, and a signed quote. A person reads any source free at its `url`. Paying at this door is not open yet; an agent with a naulon account buys the same sources with `POST /_naulon/v1/ask` and the quote.","tags":["Agents"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","maxLength":2000},"payer":{"type":"string","description":"The 0x address that will pay. Optional; lets you erase every question it asked."},"budgetUsdc":{"type":"number","exclusiveMinimum":0,"description":"The most to spend on this question. Capped by the fleet's ceiling."},"rule":{"$ref":"#/components/schemas/BuyRule"}},"required":["question"]}}}},"responses":{"200":{"description":"No licensed source covers the question. Nothing to buy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402NoMatch"}}}},"400":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"402":{"description":"The menu.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Quote"}}}},"404":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Too many questions from this address. `retry-after` says when.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retryAfterSec":{"type":"integer"}},"required":["error","retryAfterSec"]}}}},"502":{"description":"The survey failed. Nothing was charged.","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":["string","null"],"description":"Null when nothing about the question was stored."},"eraseToken":{"type":"string","description":"Spend once at `POST /_naulon/x402/forget` to erase this question."},"privacy":{"type":"string","description":"What is kept, for how long, and how to erase it."},"error":{"type":"string","enum":["survey_failed"]},"message":{"type":"string"}},"required":["requestId","privacy","error","message"]}}}}}}},"/_naulon/x402/forget/message":{"get":{"summary":"The message to sign to erase a payer's questions","tags":["Agents"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"payer","in":"query"}],"responses":{"200":{"description":"Sign `message` with the payer's key within ten minutes.","content":{"application/json":{"schema":{"type":"object","properties":{"payer":{"type":"string"},"issuedAt":{"type":"integer"},"message":{"type":"string"}},"required":["payer","issuedAt","message"]}}}},"400":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/x402/forget":{"post":{"summary":"Erase questions","description":"Send `{token}` (the `eraseToken` a menu returned) to erase that one question, or `{payer, issuedAt, signature}` to erase every question from that address.","tags":["Agents"],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"token":{"type":"string"}},"required":["token"]},{"type":"object","properties":{"payer":{"type":"string"},"issuedAt":{"type":"integer"},"signature":{"type":"string"}},"required":["payer","issuedAt","signature"]}]}}}},"responses":{"200":{"description":"How many questions were erased. An unknown or spent token erases 0.","content":{"application/json":{"schema":{"type":"object","properties":{"erased":{"type":"integer"},"payer":{"type":"string"}},"required":["erased"]}}}},"400":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Refused.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Too many questions from this address. `retry-after` says when.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retryAfterSec":{"type":"integer"}},"required":["error","retryAfterSec"]}}}}}}}},"webhooks":{"anomaly.detected":{"post":{"tags":["Webhooks"],"summary":"A traffic or earnings anomaly crossed a threshold you set.","description":"Fires once per breach per throttle window — a standing breach does not re-send on every sweep. Delivered to a signed `raw` endpoint, or as a one-line summary to a Slack, Discord or Teams channel.","parameters":[{"schema":{"type":"string","description":"`t=<unix-seconds>,v1=<hex>` — HMAC-SHA256 over `` `${t}.${rawBody}` `` with the endpoint's secret. Recompute over the RAW bytes and compare in constant time; reject beyond ~5 minutes of clock skew.","example":"t=1719000000,v1=6f1c…"},"required":true,"description":"`t=<unix-seconds>,v1=<hex>` — HMAC-SHA256 over `` `${t}.${rawBody}` `` with the endpoint's secret. Recompute over the RAW bytes and compare in constant time; reject beyond ~5 minutes of clock skew.","name":"Naulon-Signature","in":"header"},{"schema":{"type":"string","description":"This delivery's id."},"required":true,"description":"This delivery's id.","name":"Naulon-Id","in":"header"},{"schema":{"type":"string","description":"The event type, so a handler can dispatch without parsing the body.","example":"settlement.completed"},"required":true,"description":"The event type, so a handler can dispatch without parsing the body.","name":"Naulon-Event","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"This delivery's id. Also sent as `Naulon-Id`.","example":"dlv_01J8QF3M2K7X"},"type":{"type":"string","enum":["anomaly.detected"]},"eventId":{"type":"string","description":"Stable per underlying occurrence, so a retry or a racing sweep is the same event. De-duplicate on this, never on `id`.","example":"anomaly:alr_9f2:29650"},"createdAt":{"type":"integer","description":"Unix epoch milliseconds.","example":1719000000000},"data":{"type":"object","properties":{"metric":{"type":"string","example":"denied_reads"},"detail":{"type":"string","description":"The human sentence the alert email also carries.","example":"142 denied reads in the last 24h, over a threshold of 50"},"rangeKey":{"type":"string","description":"The window the breach was measured over.","example":"24h"},"threshold":{"type":"number","description":"The value you set, that the metric crossed.","example":50}},"required":["metric","detail","rangeKey","threshold"],"description":"What tripped, and against which threshold."}},"required":["id","type","eventId","createdAt","data"]}}}},"responses":{"200":{"description":"Any 2xx marks the delivery successful. The body is ignored."},"default":{"description":"A non-2xx is recorded as a failed delivery and shown in the endpoint's delivery log."}}}},"settlement.completed":{"post":{"tags":["Webhooks"],"summary":"A payout settled to an author on one of your sites.","description":"The `data` shape depends on the endpoint's payload profile: `detailed` (the default for new endpoints) carries the gross, a leg per payee and the window; `summary` carries only the count. Chat channels always get the one-line summary regardless of profile. Switching profile takes effect on the next delivery, and because the signature covers the exact bytes you receive, either shape verifies.","parameters":[{"schema":{"type":"string","description":"`t=<unix-seconds>,v1=<hex>` — HMAC-SHA256 over `` `${t}.${rawBody}` `` with the endpoint's secret. Recompute over the RAW bytes and compare in constant time; reject beyond ~5 minutes of clock skew.","example":"t=1719000000,v1=6f1c…"},"required":true,"description":"`t=<unix-seconds>,v1=<hex>` — HMAC-SHA256 over `` `${t}.${rawBody}` `` with the endpoint's secret. Recompute over the RAW bytes and compare in constant time; reject beyond ~5 minutes of clock skew.","name":"Naulon-Signature","in":"header"},{"schema":{"type":"string","description":"This delivery's id."},"required":true,"description":"This delivery's id.","name":"Naulon-Id","in":"header"},{"schema":{"type":"string","description":"The event type, so a handler can dispatch without parsing the body.","example":"settlement.completed"},"required":true,"description":"The event type, so a handler can dispatch without parsing the body.","name":"Naulon-Event","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","description":"This delivery's id. Also sent as `Naulon-Id`.","example":"dlv_01J8QF3M2K7X"},"type":{"type":"string","enum":["settlement.completed"]},"eventId":{"type":"string","description":"Stable per underlying occurrence, so a retry or a racing sweep is the same event. De-duplicate on this, never on `id`.","example":"settlement:pub_123:29650"},"createdAt":{"type":"integer","description":"Unix epoch milliseconds.","example":1719000000000},"data":{"type":"object","properties":{"tenant":{"type":"string","example":"acme"},"host":{"type":"string","example":"acme.example.com"},"window":{"type":"object","properties":{"toMs":{"type":"integer","example":1719000000000},"spanMs":{"type":"integer","example":60000}},"required":["toMs","spanMs"]},"citations":{"type":"object","properties":{"settled":{"type":"integer","example":3}},"required":["settled"]},"gross":{"type":"object","properties":{"microUsdc":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":8800},"usdc":{"type":"string","description":"Formatted convenience only. `microUsdc` is the source of truth; never parse this back.","example":"0.008800"}},"required":["microUsdc","usdc"]},"legs":{"type":"array","items":{"$ref":"#/components/schemas/SettlementLeg"},"description":"`gross.microUsdc` is the sum of these."},"settlementRefs":{"type":"array","items":{"type":"string","example":"0xab12..."}}},"required":["tenant","host","window","citations","gross","legs","settlementRefs"],"description":"The full settlement."}},"required":["id","type","eventId","createdAt","data"]},{"type":"object","properties":{"id":{"type":"string","description":"This delivery's id. Also sent as `Naulon-Id`.","example":"dlv_01J8QF3M2K7X"},"type":{"type":"string","enum":["settlement.completed"]},"eventId":{"type":"string","description":"Stable per underlying occurrence, so a retry or a racing sweep is the same event. De-duplicate on this, never on `id`.","example":"settlement:pub_123:29650"},"createdAt":{"type":"integer","description":"Unix epoch milliseconds.","example":1719000000000},"data":{"type":"object","properties":{"tenant":{"type":"string","example":"acme"},"announced":{"type":"integer","example":3}},"required":["tenant","announced"],"description":"The count only."}},"required":["id","type","eventId","createdAt","data"]}]}}}},"responses":{"200":{"description":"Any 2xx marks the delivery successful. The body is ignored."},"default":{"description":"A non-2xx is recorded as a failed delivery and shown in the endpoint's delivery log."}}}}}}