{"openapi":"3.1.0","info":{"title":"De Ring API","version":"1.0.0","description":"Complete agent contract for discovery, membership, widgets, tracking, Base Pay throne seizures, moderation, refunds and ledger-backed payouts. USDC on Base, no chargebacks, the throne is final."},"servers":[{"url":"https://dering.lol"}],"tags":[{"name":"Discovery"},{"name":"Public"},{"name":"Images"},{"name":"Membership"},{"name":"Widgets"},{"name":"Tracking"},{"name":"Takeovers"},{"name":"Ringmaster"},{"name":"Payouts"}],"components":{"securitySchemes":{"auth0":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Auth0 API access token obtained through De Ring's interactive login. Ringmaster operations additionally require the configured ringmaster email."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["validation_failed"]},"message":{"type":"string"},"details":{"type":"array","items":{},"description":"Present for structured validation errors."}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Creative":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"line":{"type":"string"},"destinationUrl":{"type":"string","format":"uri"},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","line","destinationUrl","imageUrl"],"additionalProperties":false},"Throne":{"type":"object","properties":{"reignId":{"type":"string","format":"uuid"},"creative":{"$ref":"#/components/schemas/Creative"},"amountPaidDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"startedAt":{"type":"string","format":"date-time"},"currentPriceDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"minimumBidDollars":{"type":"integer","minimum":1},"mode":{"type":"string","enum":["paid","rotation"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["reignId","creative","amountPaidDollars","startedAt","currentPriceDollars","minimumBidDollars","mode","expiresAt"],"additionalProperties":false},"FeedEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"newKing":{"type":"string"},"previousKing":{"type":"string"},"amountDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"createdAt":{"type":"string","format":"date-time"},"isNewMember":{"type":"boolean"}},"required":["id","newKing","previousKing","amountDollars","createdAt","isNewMember"],"additionalProperties":false},"EventReceipt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"newKing":{"type":"string"},"previousKing":{"type":"string"},"amountDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"createdAt":{"type":"string","format":"date-time"},"isNewMember":{"type":"boolean"},"newReignId":{"type":"string","format":"uuid"},"previousReignId":{"type":"string","format":"uuid"},"line":{"type":"string"},"destinationUrl":{"type":"string","format":"uri"},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"durationSeconds":{"type":"integer","minimum":0}},"required":["id","newKing","previousKing","amountDollars","createdAt","isNewMember","newReignId","previousReignId","line","destinationUrl","imageUrl","durationSeconds"],"additionalProperties":false},"MemberSite":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"memberId":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string"},"trafficTier":{"type":"string"},"foundingNumber":{"anyOf":[{"type":"integer"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","memberId","slug","name","hostname","trafficTier","foundingNumber","imageUrl","tagline"],"additionalProperties":false},"LiveStatsMember":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"name":{"type":"string"},"foundingNumber":{"anyOf":[{"type":"integer"},{"type":"null"}]},"sites":{"type":"array","items":{"type":"string"}},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"poolPercentage":{"type":"number"},"projectedPayoutDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"payoutDueDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"eligible":{"type":"boolean"}},"required":["memberId","name","foundingNumber","sites","impressions","clicks","poolPercentage","projectedPayoutDollars","payoutDueDollars","eligible"],"additionalProperties":false},"LiveStats":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"reign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kingName":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"minimumBidDollars":{"type":"integer"}},"required":["id","kingName","startedAt","minimumBidDollars"],"additionalProperties":false},"memberPoolRate":{"type":"number","examples":[0.7]},"projectedPoolDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"totals":{"type":"object","properties":{"impressions":{"type":"integer"},"eligibleImpressions":{"type":"integer"},"clicks":{"type":"integer"},"payoutsDueDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."}},"required":["impressions","eligibleImpressions","clicks","payoutsDueDollars"],"additionalProperties":false},"members":{"type":"array","items":{"$ref":"#/components/schemas/LiveStatsMember"}}},"required":["generatedAt","reign","memberPoolRate","projectedPoolDollars","totals","members"],"additionalProperties":false},"AuthPrincipal":{"type":"object","properties":{"email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"memberId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"isRingmaster":{"type":"boolean"},"subject":{"type":"string"}},"required":["email","memberId","isRingmaster","subject"],"additionalProperties":false},"AnonymousPrincipal":{"type":"object","properties":{"email":{"type":"null"},"memberId":{"type":"null"},"isRingmaster":{"const":false}},"required":["email","memberId","isRingmaster"],"additionalProperties":false},"MemberApplication":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80,"description":"Member/person display name."},"siteName":{"type":"string","minLength":2,"maxLength":80},"hostname":{"type":"string","examples":["example.com"],"description":"Bare approved hostname; no scheme or path."},"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"],"description":"USDC payout address on Base. The applicant attests it is correct."},"tagline":{"type":"string","minLength":10,"maxLength":180},"imageDataUrl":{"type":"string","maxLength":2000000,"description":"A client-cropped image data URL. The server normalizes it to WebP."}},"required":["name","siteName","hostname","payoutAddress","tagline","imageDataUrl"],"additionalProperties":false},"MemberCard":{"type":"object","properties":{"tagline":{"type":"string","minLength":10,"maxLength":180},"imageDataUrl":{"type":"string","maxLength":2000000,"description":"A client-cropped image data URL. The server normalizes it to WebP."}},"required":["tagline","imageDataUrl"],"additionalProperties":false},"WidgetEmbed":{"type":"object","properties":{"variant":{"type":"string","enum":["banner","sidebar","card","strip"]},"label":{"type":"string"},"placement":{"type":"string"},"height":{"type":"integer"},"code":{"type":"string"},"previewUrl":{"type":"string"}},"required":["variant","label","placement","height","code","previewUrl"],"additionalProperties":false},"DashboardSite":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string"},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"scriptEmbed":{"type":"string"},"widgetEmbeds":{"type":"array","items":{"$ref":"#/components/schemas/WidgetEmbed"}},"imageEmbed":{"type":"string"}},"required":["id","slug","name","hostname","tagline","imageUrl","impressions","clicks","scriptEmbed","widgetEmbeds","imageEmbed"],"additionalProperties":false},"LedgerEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amountDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"impressions":{"type":"integer"},"kind":{"type":"string"},"note":{"anyOf":[{"type":"string"},{"type":"null"}]},"payoutId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"payoutStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","amountDollars","impressions","kind","note","payoutId","payoutStatus","createdAt"],"additionalProperties":false},"Dashboard":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"name":{"type":"string"},"balanceDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"lifetimeEarningsDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"sites":{"type":"array","items":{"$ref":"#/components/schemas/DashboardSite"}},"ledger":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}}},"required":["memberId","name","balanceDollars","lifetimeEarningsDollars","sites","ledger"],"additionalProperties":false},"ApplicationDecision":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]},"reason":{"type":"string","maxLength":500}},"required":["decision"],"additionalProperties":false},"ApplicationRecord":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"siteName":{"type":"string"},"hostname":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"payoutAddress":{"anyOf":[{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"]},{"type":"null"}]},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}]},"imageDataUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"decisionReason":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","email","siteName","hostname","slug","status","payoutAddress","tagline","imageDataUrl","decisionReason","createdAt"],"additionalProperties":false},"KillReign":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"additionalProperties":false},"RefundConfirmation":{"type":"object","properties":{"transactionId":{"type":"string","minLength":3,"maxLength":200},"note":{"type":"string","maxLength":500}},"required":["transactionId"],"additionalProperties":false},"PendingRefund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"provider":{"type":"string"},"providerTransactionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"payerAddress":{"anyOf":[{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"]},{"type":"null"}]},"amountDollars":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"kingName":{"type":"string"},"queuedAt":{"type":"string","format":"date-time"}},"required":["id","provider","providerTransactionId","payerAddress","amountDollars","kingName","queuedAt"],"additionalProperties":false},"MemberPayout":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"memberId":{"type":"string","format":"uuid"},"memberName":{"type":"string"},"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"]},"amountUsdc":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"status":{"type":"string","enum":["reserved","initiated","submitted","completed","cancelled"]},"transactionId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","memberId","memberName","payoutAddress","amountUsdc","status","transactionId"],"additionalProperties":false},"PayoutCandidate":{"type":"object","properties":{"memberId":{"type":"string","format":"uuid"},"memberName":{"type":"string"},"payoutAddress":{"anyOf":[{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"]},{"type":"null"}]},"balanceUsdc":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"pendingPayoutId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"pendingAmountUsdc":{"anyOf":[{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},{"type":"null"}]},"pendingStatus":{"anyOf":[{"type":"string"},{"type":"null"}]},"pendingTransactionId":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["memberId","memberName","payoutAddress","balanceUsdc","pendingPayoutId","pendingAmountUsdc","pendingStatus","pendingTransactionId"],"additionalProperties":false},"PayoutHistory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"memberName":{"type":"string"},"payoutAddress":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"]},"amountUsdc":{"type":"number","minimum":0,"description":"USDC amount. Responses may contain values to six decimal places."},"status":{"type":"string"},"transactionId":{"anyOf":[{"type":"string"},{"type":"null"}]},"creditCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","memberName","payoutAddress","amountUsdc","status","transactionId","creditCount","createdAt","completedAt"],"additionalProperties":false},"PayoutCompletion":{"type":"object","properties":{"transactionId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["transactionId"],"additionalProperties":false},"PayoutReset":{"type":"object","properties":{"confirmation":{"const":"NO_PAYMENT_EXISTS"}},"required":["confirmation"],"additionalProperties":false},"TakeoverCheckout":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"Public king/creative name."},"line":{"type":"string","minLength":1,"maxLength":120},"destinationUrl":{"type":"string","format":"uri","pattern":"^https://"},"imageDataUrl":{"type":"string","maxLength":2000000,"description":"A client-cropped image data URL. The server normalizes it to WebP."},"contactEmail":{"type":"string","format":"email","description":"Optional contact only; Auth0 is identity."},"bidDollars":{"type":"integer","minimum":1,"description":"Whole USDC dollars."}},"required":["name","line","destinationUrl","imageDataUrl","bidDollars"],"additionalProperties":false},"PaymentCompletion":{"type":"object","properties":{"paymentId":{"type":"string","format":"uuid"},"transactionId":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["paymentId","transactionId"],"additionalProperties":false},"TakeoverStatus":{"type":"object","properties":{"status":{"type":"string","enum":["moderating","installed","refund_pending","conflict","ignored"]}},"required":["status"],"additionalProperties":false},"FunnelEvent":{"type":"object","properties":{"eventType":{"type":"string","enum":["stage_visit","seize_clicked","payment_initiated"]},"paymentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["eventType"],"additionalProperties":false},"WidgetConfiguration":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"hostname":{"type":"string"}},"required":["id","slug","name","hostname"],"additionalProperties":false},"constraint":{"type":"string"},"scripts":{"type":"array","items":{"$ref":"#/components/schemas/WidgetEmbed"}},"newsletterImage":{"type":"object","properties":{"code":{"type":"string"},"imageUrl":{"type":"string"},"clickUrl":{"type":"string"},"reignId":{"type":"string","format":"uuid"}},"required":["code","imageUrl","clickUrl","reignId"],"additionalProperties":false},"stateUrl":{"type":"string"}},"required":["site","constraint","scripts","newsletterImage","stateUrl"],"additionalProperties":false}}},"paths":{"/api":{"get":{"tags":["Discovery"],"operationId":"discoverApi","summary":"Discover every agent workflow","responses":{"200":{"description":"Capability catalog","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/health":{"get":{"tags":["Public"],"operationId":"health","summary":"Check service health","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"service":{"const":"dering"}},"required":["ok","service"],"additionalProperties":false}}}}}}},"/api/throne":{"get":{"tags":["Public"],"operationId":"getThrone","summary":"Get the current throne, creative, reign and price","responses":{"200":{"description":"Current throne","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Throne"}}}}}}},"/api/feed":{"get":{"tags":["Public"],"operationId":"getFeed","summary":"List recent takeover events","responses":{"200":{"description":"Newest first","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FeedEvent"}}}}}}}},"/api/stats/live":{"get":{"tags":["Public"],"operationId":"getLiveStats","summary":"Get public traffic, pool shares and balances","responses":{"200":{"description":"Live statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveStats"}}}}}}},"/api/members":{"get":{"tags":["Public"],"operationId":"listMembers","summary":"List active member sites","responses":{"200":{"description":"Active sites","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MemberSite"}}}}}}}},"/api/events/{eventId}":{"get":{"tags":["Public"],"operationId":"getEventReceipt","summary":"Get a takeover receipt","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventReceipt"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/member-sites/{siteId}/card.webp":{"get":{"tags":["Images"],"operationId":"getMemberCardImage","summary":"Get a normalized member-site image","parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"WebP image","content":{"image/webp":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/creatives/{creativeId}/card.webp":{"get":{"tags":["Images"],"operationId":"getCreativeImage","summary":"Get a normalized throne creative image","parameters":[{"name":"creativeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"WebP image","content":{"image/webp":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/me":{"get":{"tags":["Membership"],"operationId":"getIdentity","summary":"Resolve an optional Auth0 identity","security":[{"auth0":[]},{}],"responses":{"200":{"description":"Authenticated principal or anonymous state","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AuthPrincipal"},{"$ref":"#/components/schemas/AnonymousPrincipal"}]}}}}}}},"/api/member-applications":{"post":{"tags":["Membership"],"operationId":"applyToRing","summary":"Apply with a site","security":[{"auth0":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberApplication"},"example":{"name":"Jane","siteName":"Example","hostname":"example.com","payoutAddress":"0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38","tagline":"Independent software and useful experiments.","imageDataUrl":"data:image/webp;base64,..."}}}},"responses":{"201":{"description":"Application queued","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"const":"pending"}},"required":["id","status"],"additionalProperties":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/member/dashboard":{"get":{"tags":["Membership"],"operationId":"getMemberDashboard","summary":"Get account, sites, embeds, traffic, balance and ledger","security":[{"auth0":[]}],"responses":{"200":{"description":"Member dashboard","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dashboard"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/member/sites/{siteId}/card":{"put":{"tags":["Membership"],"operationId":"updateMemberCard","summary":"Replace a site's tagline and cropped image","security":[{"auth0":[]}],"parameters":[{"name":"siteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberCard"},"example":{"tagline":"Independent software and useful experiments.","imageDataUrl":"data:image/webp;base64,..."}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"updated"}},"required":["status"],"additionalProperties":false},"example":{"status":"updated"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/widgets/{memberSlug}":{"get":{"tags":["Widgets"],"operationId":"getWidgetConfiguration","summary":"Get copy-ready web and newsletter widget configuration","parameters":[{"name":"memberSlug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"Widget configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetConfiguration"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/widget/state":{"get":{"tags":["Widgets"],"operationId":"getWidgetState","summary":"Get live throne state for a widget","parameters":[{"name":"m","in":"query","required":true,"schema":{"type":"string"},"description":"Approved member-site slug"},{"name":"previous","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Previously rendered reign; a changed reign records one impression"}],"responses":{"200":{"description":"Throne plus reign-pinned clickUrl","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Throne"},{"type":"object","properties":{"clickUrl":{"type":"string","format":"uri"}},"required":["clickUrl"],"additionalProperties":false}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/funnel":{"post":{"tags":["Tracking"],"operationId":"trackTakeoverFunnel","summary":"Record an anonymous takeover funnel event","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunnelEvent"},"example":{"eventType":"seize_clicked"}}}},"responses":{"204":{"description":"Recorded"},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/takeovers/eligibility":{"get":{"tags":["Takeovers"],"operationId":"getTakeoverEligibility","summary":"Check whether the account may seize","security":[{"auth0":[]}],"responses":{"200":{"description":"Eligibility and current throne","content":{"application/json":{"schema":{"type":"object","properties":{"canSeize":{"type":"boolean"},"reason":{"anyOf":[{"const":"already_king"},{"type":"null"}]},"throne":{"$ref":"#/components/schemas/Throne"}},"required":["canSeize","reason","throne"],"additionalProperties":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/takeovers/checkout":{"post":{"tags":["Takeovers"],"operationId":"createTakeoverCheckout","summary":"Create an authenticated Base Pay quote","description":"USDC on Base, no chargebacks, the throne is final. Payment does not bypass post-payment agent moderation.","security":[{"auth0":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeoverCheckout"},"example":{"name":"Example King","line":"Useful independent software.","destinationUrl":"https://example.com","imageDataUrl":"data:image/webp;base64,...","bidDollars":12}}}},"responses":{"200":{"description":"Base Pay or local-test quote","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["base_pay","mock"]},"paymentId":{"type":"string","format":"uuid"},"amountDollars":{"type":"integer"},"recipient":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","examples":["0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38"]},"testnet":{"type":"boolean"}},"required":["provider","paymentId","amountDollars"],"additionalProperties":false},"example":{"provider":"base_pay","paymentId":"018f05d0-8a3f-7000-8000-000000000001","amountDollars":12,"recipient":"0xd117cdAd116599232b8fc24d0B3CfD2179D0eB38","testnet":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Stale bid or current king","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Input or deterministic creative validation failed","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/takeovers/complete":{"post":{"tags":["Takeovers"],"operationId":"completeTakeoverPayment","summary":"Verify Base payment and begin agent moderation","security":[{"auth0":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCompletion"},"example":{"paymentId":"018f05d0-8a3f-7000-8000-000000000001","transactionId":"0x0000000000000000000000000000000000000000000000000000000000000001"}}}},"responses":{"200":{"description":"Moderation/install state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeoverStatus"},"example":{"status":"moderating"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Payment not complete","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"pending"},"reason":{"type":"string"}},"required":["status","reason"],"additionalProperties":false}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/takeovers/{paymentId}/status":{"get":{"tags":["Takeovers"],"operationId":"getTakeoverStatus","summary":"Read and advance paid-creative moderation","description":"Refresh this query until installed or refund_pending. Moderation is idempotent and keyed by paymentId.","security":[{"auth0":[]}],"parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TakeoverStatus"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/applications":{"get":{"tags":["Ringmaster"],"operationId":"listApplications","summary":"List membership applications","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","responses":{"200":{"description":"Applications","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationRecord"}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/applications/{applicationId}":{"post":{"tags":["Ringmaster"],"operationId":"decideApplication","summary":"Approve or reject an application","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","parameters":[{"name":"applicationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationDecision"},"example":{"decision":"approved","reason":"Site verified."}}}},"responses":{"200":{"description":"Decision recorded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["approved","rejected"]}},"required":["status"],"additionalProperties":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/kill":{"post":{"tags":["Ringmaster"],"operationId":"vacateThrone","summary":"Vacate the throne and queue its refund","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KillReign"},"example":{"reason":"Destination began serving malware."}}}},"responses":{"200":{"description":"Vacated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"vacated"},"refund":{"const":"queued"}},"required":["status","refund"],"additionalProperties":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/refunds":{"get":{"tags":["Ringmaster"],"operationId":"listRefunds","summary":"List manual USDC refunds awaiting proof","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","responses":{"200":{"description":"Pending refunds","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PendingRefund"}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/refunds/{paymentId}":{"post":{"tags":["Ringmaster"],"operationId":"confirmRefund","summary":"Attach proof and mark a refund complete","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundConfirmation"},"example":{"transactionId":"0xrefund-proof","note":"Manual USDC refund on Base."}}}},"responses":{"200":{"description":"Refunded","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"refunded"}},"required":["status"],"additionalProperties":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/payouts":{"get":{"tags":["Payouts"],"operationId":"listPayoutCandidates","summary":"List member balances and open payout reservations","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","responses":{"200":{"description":"Payout candidates","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PayoutCandidate"}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/payout-history":{"get":{"tags":["Payouts"],"operationId":"listPayoutHistory","summary":"List the latest 100 payout records and proofs","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","responses":{"200":{"description":"Payout history","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PayoutHistory"}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/payouts/members/{memberId}/quote":{"post":{"tags":["Payouts"],"operationId":"reserveMemberPayout","summary":"Transactionally reserve every unpaid ledger credit for a member","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Reserved payout plus rail","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/MemberPayout"},{"type":"object","properties":{"provider":{"type":"string","enum":["base_pay","mock"]},"testnet":{"type":"boolean"}},"required":["provider","testnet"],"additionalProperties":false}]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/payouts/{payoutId}/initiate":{"post":{"tags":["Payouts"],"operationId":"initiatePayout","summary":"Move a reserved payout into the payment step","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Initiated payout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberPayout"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/payouts/{payoutId}/reset":{"post":{"tags":["Payouts"],"operationId":"resetUnconfirmedPayout","summary":"Reset only after confirming no on-chain payment exists","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutReset"},"example":{"confirmation":"NO_PAYMENT_EXISTS"}}}},"responses":{"200":{"description":"Reset","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"reserved"}},"required":["status"],"additionalProperties":false}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"State conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/ringmaster/payouts/{payoutId}/complete":{"post":{"tags":["Payouts"],"operationId":"completePayout","summary":"Verify a Base transaction and atomically satisfy its reserved ledger entries","security":[{"auth0":[]}],"description":"Requires the configured ringmaster Auth0 identity.","parameters":[{"name":"payoutId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutCompletion"},"example":{"transactionId":"0x0000000000000000000000000000000000000000000000000000000000000001"}}}},"responses":{"200":{"description":"Completed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"completed"}},"required":["status"],"additionalProperties":false},"example":{"status":"completed"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Transaction absent, wrong or already claimed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"pending"},"reason":{"type":"string"}},"required":["status","reason"],"additionalProperties":false}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/widget.js":{"get":{"tags":["Widgets"],"operationId":"getWidgetScript","summary":"Get the script-tag widget loader","parameters":[{"name":"m","in":"query","required":true,"schema":{"type":"string"}},{"name":"v","in":"query","required":false,"schema":{"type":"string","enum":["banner","sidebar","card","strip"]}}],"responses":{"200":{"description":"JavaScript","content":{"application/javascript":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/widget-live":{"get":{"tags":["Widgets"],"operationId":"getWidgetDocument","summary":"Get the live widget document and count its impression","description":"Browser Referer must match the approved site hostname.","parameters":[{"name":"m","in":"query","required":true,"schema":{"type":"string"}},{"name":"v","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Widget HTML","content":{"text/html":{"schema":{"type":"string"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/widget-frame":{"get":{"tags":["Widgets"],"operationId":"getStaticWidgetFrame","summary":"Render the server-side widget frame and count its impression","description":"Browser Referer must match the approved site hostname.","parameters":[{"name":"m","in":"query","required":true,"schema":{"type":"string"}},{"name":"v","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Widget HTML","content":{"text/html":{"schema":{"type":"string"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/widget-preview":{"get":{"tags":["Widgets"],"operationId":"previewWidget","summary":"Preview a widget without counting inventory","parameters":[{"name":"v","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Preview HTML","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/widgets":{"get":{"tags":["Widgets"],"operationId":"getWidgetGallery","summary":"Get the contextual widget gallery","responses":{"200":{"description":"Gallery HTML","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/throne.png":{"get":{"tags":["Widgets"],"operationId":"getNewsletterImage","summary":"Render and count a reign-pinned newsletter image","parameters":[{"name":"m","in":"query","required":true,"schema":{"type":"string"}},{"name":"r","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PNG image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/r":{"get":{"tags":["Tracking"],"operationId":"recordWidgetClick","summary":"Record a reign-pinned click and redirect","parameters":[{"name":"m","in":"query","required":true,"schema":{"type":"string"}},{"name":"r","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"c","in":"query","required":false,"schema":{"type":"string","enum":["widget","image"]}}],"responses":{"302":{"description":"Redirect to the reign destination or ring rotation target","headers":{"Location":{"schema":{"type":"string","format":"uri-reference"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ring/random":{"get":{"tags":["Public"],"operationId":"visitRandomMember","summary":"Redirect to a random active ring member","responses":{"302":{"description":"Member or /ring redirect"}}}},"/events/{eventId}":{"get":{"tags":["Public"],"operationId":"getShareableEventPage","summary":"Get an HTML takeover receipt with social metadata","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Receipt HTML","content":{"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{eventId}/og.png":{"get":{"tags":["Images"],"operationId":"getEventOgImage","summary":"Get the immutable social image for a takeover receipt","parameters":[{"name":"eventId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PNG image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}