{"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":"Webhooks","description":"What naulon POSTs to you. Every signed delivery carries the same envelope; the event's own fields are under `data`."}],"components":{"securitySchemes":{"nlnLive":{"type":"http","scheme":"bearer","description":"An `nln_live_` publisher key."}},"schemas":{"VerifyReceipt":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"settlementRef":{"type":"string"},"payer":{"type":"string"},"responseHeader":{"type":"string"},"licenseJws":{"type":"string"},"chargedMicro":{"type":"string"}},"required":["ok"]},"VerifyError":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["ok","error"]},"VerifyRequest":{"type":"object","properties":{"payment":{"type":"string","minLength":1,"description":"The buyer's x402 payment payload (required)."},"legs":{"type":"array","items":{},"description":"Settlement legs, validated against the signature (required)."},"quote":{"description":"The gate Quote that priced the resource (required)."},"resource":{"type":"string","format":"uri","example":"https://your-site.com/articles/x"},"agent":{"$ref":"#/components/schemas/ObservedAgent"}}},"ObservedAgent":{"type":"object","properties":{"ua":{"type":"string"},"classifyReason":{"type":"string"},"verified":{"type":"boolean"},"verifiedAgent":{"type":"string"},"sigInvalid":{"type":"boolean"}},"description":"Who the caller was, as the publisher's own classifier saw them. Telemetry for the audit plane — never used for authorization."},"Quote":{"type":"object","properties":{"price":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500}},"required":["price"],"additionalProperties":{},"description":"Custody-free quote: payTo addresses + price. `204` = free (no toll)."},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"EnforcementConfig":{"type":"object","properties":{"enforcement":{"type":"object","properties":{},"additionalProperties":{}}},"required":["enforcement"],"additionalProperties":{},"description":"The five decision inputs the in-app enforcer reads before pricing, plus this publisher's x402 manifest. Carries no price, no chain, and no secret."},"ObserveAccepted":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"accepted":{"type":"integer"}},"required":["ok","accepted"]},"ObserveError":{"type":"object","properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["ok","error"]},"ObservationReport":{"type":"object","properties":{"resource":{"type":"string","format":"uri","example":"https://your-site.com/articles/x","description":"The URL the decision was made for. Its host must be owned by this key's tenant."},"slug":{"type":"string","example":"articles/x","description":"The article slug that was priced. Empty for a gated non-article path."},"verdict":{"type":"string","enum":["served-free","agent-reread","denied","blocked","paid","payment-failed","unservable"],"example":"denied","description":"What happened. `paid` and `payment-failed` are NOT accepted here — the cloud writes those itself from the /verify settle outcome."},"classifiedAs":{"type":"string","enum":["human","agent"],"example":"agent"},"kind":{"type":"string","enum":["read","citation"],"example":"read"},"priceMicro":{"type":"integer","minimum":0,"example":1000,"description":"What the request would have paid, in integer micro-USDC. Drives the 'earnings missed' figure."},"at":{"type":"integer","exclusiveMinimum":0,"description":"When the decision happened (epoch ms). Defaults to now; clamped to a sane window."},"agent":{"$ref":"#/components/schemas/ObservedAgent"}},"required":["resource","verdict","classifiedAs"]},"LicenceQuote":{"type":"object","properties":{"priceMicro":{"type":"number"},"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","patterns","terms","period","resourceCount","legs"]},"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"},"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","resourceCount","legs","settlementRef","settlementRefKind","boughtAt"]},"EnforcementStatusResponse":{"type":"object","properties":{"hosts":{"type":"array","items":{"$ref":"#/components/schemas/EnforcementStatusRow"}},"attention":{"type":"boolean"}},"required":["hosts","attention"]},"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"]},"LicenseCheckResult":{"type":"object","properties":{"entitled":{"type":"boolean"}},"required":["entitled"]},"LicenseCheckBody":{"type":"object","properties":{"license":{"type":"string","minLength":1},"resource":{"type":"string","format":"uri"},"slug":{"type":"string","minLength":1},"kind":{"type":"string","enum":["read","citation"],"default":"read"},"proof":{"type":"string"}},"required":["license","resource","slug"]},"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/TenantLedger"}},"recent":{"type":"array","items":{"$ref":"#/components/schemas/Crossing"}},"nextCursor":{"type":"number"}},"required":["generatedAt","window","totals","tenants","recent"]},"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"]},"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"},"kind":{"type":"string","enum":["read","citation"]},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"at":{"type":"number"}},"required":["host","slug","kind","micro","at"]},"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"},"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"},"verified":{"type":"boolean"}},"required":["agent","hits","denied","paid"]}},"recent":{"type":"array","items":{"$ref":"#/components/schemas/AuditObservation"}},"nextCursor":{"type":"number"},"truncated":{"type":"boolean"}},"required":["generatedAt","window","totals","byAgent","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"}},"required":["observations","agentHits","denied","paid","servedFree","paymentFailed","missedMicroUsdc","failedMicroUsdc","failedByReason","earnedMicroUsdc","verifiedHits","masqueradeAttempts"]},"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"]},"AuditObservation":{"type":"object","properties":{"host":{"type":"string"},"slug":{"type":"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"]},"agentUa":{"type":"string","description":"Raw User-Agent (spoofable)."},"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."},"micro":{"type":"integer","description":"Amount in integer micro-USDC (1_000_000 = $1).","example":500},"at":{"type":"number"}},"required":["host","slug","verdict","classifiedAs","at"]},"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"]}},"parameters":{}},"paths":{"/_naulon/verify":{"post":{"summary":"Settle a payment","description":"Hosted verify of a buyer signature: settles buyer→author (custody-free), mints the re-read license, returns the receipt. Tenant-scoped — a key for site A cannot settle on site B.","tags":["Enforce"],"security":[{"nlnLive":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"Settled — the receipt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyReceipt"}}}},"400":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyError"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyError"}}}},"402":{"description":"Settlement failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyError"}}}},"403":{"description":"Not owned / suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyError"}}}}}}},"/_naulon/quote":{"get":{"summary":"Price a resource","description":"Ask what a resource costs, priced by the same resolver the gate uses. `204` means no toll (free read).","tags":["Enforce"],"security":[{"nlnLive":[]}],"parameters":[{"schema":{"type":"string","format":"uri","example":"https://your-site.com/articles/x"},"required":false,"name":"resource","in":"query"},{"schema":{"type":"string","example":"articles/x"},"required":false,"name":"slug","in":"query"},{"schema":{"type":"string","enum":["read","citation"],"example":"read"},"required":false,"name":"kind","in":"query"}],"responses":{"200":{"description":"The quote.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"204":{"description":"No toll — free read."},"400":{"description":"Missing/invalid params.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Resource not owned by this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/_naulon/enforce-config":{"get":{"summary":"The enforcement config for a resource's publisher","description":"What is in scope, who reads free, who is refused, who is charged, and which identity signs a licence — read from the tenant record, so a dashboard edit reaches an in-app enforcer without a redeploy. Cache it; it changes when a human changes it.","tags":["Enforce"],"security":[{"nlnLive":[]}],"parameters":[{"schema":{"type":"string","format":"uri","example":"https://your-site.com/articles/x"},"required":false,"name":"resource","in":"query"}],"responses":{"200":{"description":"The config.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnforcementConfig"}}}},"400":{"description":"Missing/invalid resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Resource not owned by this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/_naulon/observe":{"post":{"summary":"Report a gating decision","description":"Report what your runtime decided for a gated request, so it appears on your Audit page beside fleet-proxied traffic. Accepts one report or a batch. `paid`/`payment-failed` are written by the cloud from /verify and are refused here.","tags":["Enforce"],"security":[{"nlnLive":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ObservationReport"},{"type":"array","items":{"$ref":"#/components/schemas/ObservationReport"},"minItems":1,"maxItems":50}]}}}},"responses":{"202":{"description":"Accepted for writing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveAccepted"}}}},"400":{"description":"Bad request (incl. a money verdict).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveError"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveError"}}}},"403":{"description":"Resource not owned by this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveError"}}}}}}},"/_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"}}}},"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"}}},"required":["licences"]}}}},"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"}}}}}}},"/_naulon/enforce-status":{"get":{"summary":"Enforcement status for every owned domain","description":"The classification sweep's verdict per owned custom host (fleet / in_app / idle / conflict / unverified) with a machine-readable nextAction. Tenant-scoped by the nln_live_ key. `attention:true` = a CI should exit non-zero.","tags":["Enforce"],"security":[{"nlnLive":[]}],"responses":{"200":{"description":"Per-host status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnforcementStatusResponse"}}}},"401":{"description":"Missing or invalid key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/_naulon/license/check":{"post":{"summary":"Does this license entitle a free re-read?","description":"Verifies a presented license JWS against the minting gate's keys and the entitlement rules (issuer, audience, slug scope, kind, expiry, holder-of-key). Returns a bare boolean: a runtime only needs to know whether to serve or to price. Tenant-scoped by the nln_live_ key.","tags":["Enforce"],"security":[{"nlnLive":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseCheckBody"}}}},"responses":{"200":{"description":"The verdict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseCheckResult"}}}},"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"]}}}},"403":{"description":"Resource not owned by this key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["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":[{"nlnLive":[]}],"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":[{"nlnLive":[]}],"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":[{"nlnLive":[]}],"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":[{"nlnLive":[]}],"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":[{"nlnLive":[]}],"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 (host/slug/author/kind)."},"required":false,"description":"Segmentation key (host/slug/author/kind).","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"},"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"}],"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":[{"nlnLive":[]}],"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 (host/slug/author/kind)."},"required":false,"description":"Segmentation key (host/slug/author/kind).","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"},"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":[{"nlnLive":[]}],"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 (host/slug/author/kind)."},"required":false,"description":"Segmentation key (host/slug/author/kind).","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"},"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":[{"nlnLive":[]}],"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 (host/slug/author/kind)."},"required":false,"description":"Segmentation key (host/slug/author/kind).","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"},"required":false,"name":"limit","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":[{"nlnLive":[]}],"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 (host/slug/author/kind)."},"required":false,"description":"Segmentation key (host/slug/author/kind).","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"},"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":"Action-audit trail","tags":["Audit"],"security":[{"nlnLive":[]}],"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 (host/slug/author/kind)."},"required":false,"description":"Segmentation key (host/slug/author/kind).","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"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"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","enum":["read","citation"]},"required":false,"name":"kind","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/members":{"get":{"summary":"Author/payee roster","tags":["Members"],"security":[{"nlnLive":[]}],"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"}}}}}}}},"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."}}}}}}