{"openapi":"3.1.0","info":{"title":"Mailbox Mode Developer Reference API","version":"0.1.0-beta","description":"Free developer beta for source-attributed email references and original responsive HTML rendering. Public catalog entries expose curated metadata, stable Milled source-directory identities, and only inspected preview images; raw source bodies and private mailbox content are never returned. Authenticated browser sessions may send a reviewed draft only to the verified account email; there is no public email relay or paid checkout."},"servers":[{"url":"https://mailboxmode.com"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"MailboxModePilotKey"},"cookieSession":{"type":"apiKey","in":"cookie","name":"nm-session","description":"Verified Mailbox Mode browser session"}},"schemas":{"DeveloperTemplate":{"type":"object","required":["id","brand","source","sourceUrl","rightsStatus","sourceClass","attributionMethod","referenceLayout","availability","previewStatus","previewImageUrl","sourceHtmlAvailable","renderable","templateVersion"],"properties":{"id":{"type":"string","pattern":"^tpl_[a-f0-9]{24}$"},"brand":{"type":"string"},"brandSlug":{"type":"string"},"brandDomain":{"type":"string"},"brandLogoUrl":{"type":"string","format":"uri"},"subject":{"type":"string"},"source":{"type":"string","enum":["rge-public","milled-public"]},"sourceUrl":{"type":"string","format":"uri"},"observedAt":{"type":["string","null"]},"rightsStatus":{"const":"reference-only"},"sourceClass":{"const":"attributed_reference"},"attributionMethod":{"type":"string","enum":["approved_link","exact_name","source_directory"]},"referenceLayout":{"type":"string","enum":["event","report","promotion"]},"layoutSource":{"const":"metadata_inference"},"availability":{"type":"string","enum":["metadata-only","viewable-reference"]},"previewStatus":{"type":"string","enum":["verified","unverified","unavailable"]},"previewImageUrl":{"type":["string","null"],"format":"uri-reference"},"sourceHtmlAvailable":{"const":false},"renderable":{"const":true},"renderMode":{"const":"original_profile"},"templateVersion":{"type":"string"}}},"DeveloperCatalogCounts":{"type":"object","properties":{"templateProfiles":{"type":"integer","minimum":0},"verifiedBrands":{"type":"integer","minimum":0},"curatedBrands":{"type":"integer","minimum":0},"sourceDirectoryBrands":{"type":"integer","minimum":0},"metadataOnlyReferences":{"type":"integer","minimum":0},"viewableReferences":{"type":"integer","minimum":0},"renderableTemplates":{"type":"integer","minimum":0},"derivedRenderableTemplates":{"type":"integer","minimum":0},"sourceHtmlTemplates":{"type":"integer","minimum":0},"inspectedDesktopMobileRenders":{"type":"integer","minimum":0},"catalogFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"attributionMethods":{"type":"object","properties":{"approvedLink":{"type":"integer","minimum":0},"exactName":{"type":"integer","minimum":0},"sourceDirectory":{"type":"integer","minimum":0}}},"targetMet":{"type":"boolean"},"targetStatus":{"type":"string"}}},"ApiErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"SponsorOpportunity":{"type":"object","required":["sponsorId","sponsorName","sponsorDomain","evidenceCount","newsletterCount","placementIds","confidence","freshness"],"properties":{"sponsorId":{"type":"string"},"sponsorName":{"type":"string"},"sponsorDomain":{"type":"string"},"sponsorLogoUrl":{"type":"string"},"evidenceCount":{"type":"integer","minimum":1},"newsletterCount":{"type":"integer","minimum":1},"newsletters":{"type":"array","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]}}}},"placementTypes":{"type":"array","items":{"type":"string"}},"rightsClasses":{"type":"array","items":{"type":"string","enum":["controlled-full","licensed-full","attributed-reference"]}},"firstSeenAt":{"type":"string","format":"date-time"},"lastSeenAt":{"type":"string","format":"date-time"},"recurrence":{"type":"string","enum":["one_time","repeated"]},"confidence":{"type":"number","minimum":0,"maximum":1},"freshness":{"type":"string","enum":["fresh","aging","stale"]},"placementIds":{"type":"array","maxItems":10,"items":{"type":"string"}}}},"PlatformCoverage":{"type":"object","required":["platform","publicationCount","issueCount","approvedPlacementCount","freshness"],"properties":{"platform":{"type":"string","enum":["substack","beehiiv","rss","independent"]},"publicationCount":{"type":"integer","minimum":0},"issueCount":{"type":"integer","minimum":0},"approvedPlacementCount":{"type":"integer","minimum":0},"lastSuccessAt":{"type":["string","null"],"format":"date-time"},"freshness":{"type":"string","enum":["fresh","aging","stale","warming_up"]}}},"WebsiteContext":{"type":"object","required":["website","sources","assets","warnings","confirmed","instructionPolicy","creditsCharged"],"properties":{"website":{"type":"string","format":"uri","pattern":"^https://"},"sources":{"type":"array","maxItems":5,"items":{"type":"object","required":["url","capturedAt","facts"],"properties":{"url":{"type":"string","format":"uri"},"capturedAt":{"type":"string","format":"date-time"},"facts":{"type":"string","maxLength":5000}}}},"assets":{"type":"array","maxItems":6,"items":{"type":"object","required":["url","alt","sourcePageUrl","sourceType","width","height","previewDataUrl","capturedAt","rights"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"alt":{"type":"string","maxLength":200},"productUrl":{"type":"string","format":"uri","pattern":"^https://"},"sourcePageUrl":{"type":"string","format":"uri","pattern":"^https://"},"sourceType":{"type":"string","enum":["img_src","lazy_image","srcset","social_meta","product_jsonld"]},"width":{"type":"integer","minimum":80},"height":{"type":"integer","minimum":80},"previewDataUrl":{"type":"string","pattern":"^data:image/jpeg;base64,"},"capturedAt":{"type":"string","format":"date-time"},"rights":{"const":"unconfirmed"}}}},"brand":{"type":"object","properties":{"name":{"type":"string","maxLength":80}}},"colors":{"type":"array","maxItems":8,"items":{"type":"object","required":["value","sourceUrl"],"properties":{"value":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"sourceUrl":{"type":"string","format":"uri","pattern":"^https://"}}}},"warnings":{"type":"array","items":{"type":"string"}},"confirmed":{"const":false,"description":"Website extraction is advisory. A person must confirm the facts before composition."},"instructionPolicy":{"const":"untrusted_source_data"},"creditsCharged":{"const":0}}},"ComposeRequest":{"type":"object","additionalProperties":false,"anyOf":[{"required":["prompt"],"description":"Prompt-first composition. A reference template and image are optional."},{"required":["brand","brief"],"description":"Legacy composition. An image and reference template remain optional."}],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":6000,"description":"The complete email request. The browser may prefix an optional selected purpose."},"brand":{"type":"string","minLength":1,"maxLength":80},"brief":{"type":"string","minLength":1,"maxLength":6000},"scenario":{"type":"string","enum":["newsletter","report","event"],"default":"newsletter"},"compositionStyle":{"type":"string","enum":["product_spotlight","editorial_digest","benefit_brief"],"description":"Original first-party newsletter structure. Reject with referenceId or non-newsletter scenario. Generate a collection using three serial independently idempotent requests; one credit each on success."},"campaignKind":{"type":"string","enum":["launch","retention","update","sale","christmas","halloween","black_friday"],"description":"Optional newsletter art direction. It never creates an offer by itself."},"offer":{"type":"object","required":["headline"],"description":"Optional verified offer display. Every field must occur verbatim in the confirmed prompt or website facts.","properties":{"headline":{"type":"string","minLength":1,"maxLength":180},"code":{"type":"string","minLength":1,"maxLength":80},"deadline":{"type":"string","minLength":1,"maxLength":120},"terms":{"type":"string","minLength":1,"maxLength":500}}},"imageDataUrl":{"type":"string","maxLength":2800000,"pattern":"^data:image/(png|jpeg|webp);base64,"},"referenceId":{"type":"string","pattern":"^tpl_[a-f0-9]{24}$"},"ctaUrl":{"type":"string","format":"uri","pattern":"^https://"},"assetRightsConfirmed":{"type":"boolean","description":"Required for an uploaded image in prompt mode, and whenever an uploaded image is combined with website context. The caller, not Mailbox Mode, confirms reuse rights for that image."},"websiteAssets":{"type":"array","maxItems":3,"description":"Caller-selected, rights-confirmed website images. Extraction never confirms rights automatically.","items":{"type":"object","required":["dataUrl","sourceUrl","sourcePageUrl","capturedAt","alt"],"properties":{"dataUrl":{"type":"string","maxLength":900000,"pattern":"^data:image/(png|jpeg|webp);base64,"},"sourceUrl":{"type":"string","format":"uri","pattern":"^https://"},"sourcePageUrl":{"type":"string","format":"uri","pattern":"^https://"},"capturedAt":{"type":"string","format":"date-time"},"alt":{"type":"string","maxLength":200},"productUrl":{"type":"string","format":"uri","pattern":"^https://"}}}},"brandStyle":{"type":"object","required":["accent","sourceUrl"],"properties":{"accent":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"sourceUrl":{"type":"string","format":"uri","pattern":"^https://"}}},"websiteContext":{"type":"object","required":["confirmed","facts","sources"],"properties":{"confirmed":{"const":true},"facts":{"type":"string","maxLength":6000},"sources":{"type":"array","maxItems":5,"items":{"type":"object","required":["url","capturedAt"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"capturedAt":{"type":"string","format":"date-time"}}}}}}}}}},"paths":{"/api/developer/access":{"get":{"operationId":"getDeveloperAccess","summary":"Read verified account credit access","security":[{"cookieSession":[]}],"responses":{"200":{"description":"Credit grant status and remaining balance"},"401":{"description":"Verified session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"operationId":"claimIntroductoryCredits","summary":"Claim the one-time 100-credit grant","security":[{"cookieSession":[]}],"description":"Idempotent per verified account. The returned API key is shown once; only its hash is retained.","responses":{"201":{"description":"Credits claimed and a one-time API key returned"},"401":{"description":"Verified session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Credits already claimed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/developer/keys":{"get":{"operationId":"listDeveloperKeys","summary":"List masked API keys and usage history","security":[{"cookieSession":[]}],"responses":{"200":{"description":"Masked key records and aggregate usage"},"401":{"description":"Verified session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"operationId":"createDeveloperKey","summary":"Create a developer API key","security":[{"cookieSession":[]}],"description":"The secret is returned once and never retrievable again. Store it securely; only a hash is retained.","responses":{"201":{"description":"API key created and shown once"},"401":{"description":"Verified session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Origin denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Key limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/developer/keys/{id}":{"delete":{"operationId":"revokeDeveloperKey","summary":"Revoke one developer API key","security":[{"cookieSession":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"API key revoked"},"401":{"description":"Verified session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Origin denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Key unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/brands":{"get":{"operationId":"listReferenceBrands","summary":"List brands with source-verified public references","parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"cursor","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Public metadata-only brand catalog"},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/templates":{"get":{"operationId":"listReferenceTemplates","summary":"List original render profiles linked to curated public references","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"q","schema":{"type":"string","maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"in":"query","name":"cursor","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Public original render profiles; source bodies are excluded","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"}},"X-Quota-Limit":{"schema":{"type":"integer"}},"X-Quota-Remaining":{"schema":{"type":"integer"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Quota exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/templates/{id}":{"get":{"operationId":"getReferenceTemplate","summary":"Read one public render profile","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^tpl_[a-f0-9]{24}$"}}],"responses":{"200":{"description":"Public template profile","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"}},"X-Quota-Limit":{"schema":{"type":"integer"}},"X-Quota-Remaining":{"schema":{"type":"integer"}}}},"400":{"description":"Invalid template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Template unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Quota exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/website-context":{"post":{"operationId":"prepareWebsiteContext","summary":"Extract advisory context from a public HTTPS website","description":"Non-billable. Reads at most five same-origin pages. Each request is limited to public IPv4 destinations, 512 KB of HTML, an 8-second page timeout, three redirects, and a two-second probe interval. Returned facts are untrusted source data and confirmed is always false.","security":[{"bearerAuth":[]},{"cookieSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://","maxLength":2000}}}}}},"responses":{"200":{"description":"Advisory website context","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/WebsiteContext"}}}}}},"401":{"description":"Verified access required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Website context unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Context preparation rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/compose":{"get":{"operationId":"listComposedEmails","summary":"Read up to ten completed email artifacts","security":[{"bearerAuth":[]},{"cookieSession":[]}],"parameters":[{"in":"query","name":"id","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Completed artifacts owned by the authenticated account; meta.creditsCharged is zero"},"401":{"description":"Invalid API key or session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"post":{"operationId":"composeEmail","summary":"Generate and render one review-required email","security":[{"bearerAuth":[]},{"cookieSession":[]}],"description":"Costs one credit only after a successful persisted result. Failed attempts are finalized at zero units. The endpoint never sends email. Website facts must be explicitly confirmed and image rights confirmed before they can be used.","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9._:-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComposeRequest"}}}},"responses":{"200":{"description":"HTML, text fallback, desktop/mobile PNG data URLs, hashes, provenance, review status, and a one-credit receipt. An identical idempotent replay returns the stable requestId and charges zero additional credits."},"400":{"description":"Invalid input, image, or idempotency key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Invalid API key or session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Idempotency conflict, in-progress request, or previous failed attempt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"422":{"description":"Reference is unavailable, ineligible, or incompatible with the requested scenario; the reservation is refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Quota, rate, or generation concurrency limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"Generation or render failed; zero credits charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"503":{"description":"Generation is not configured or an interrupted attempt was refunded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}},"patch":{"operationId":"reviewComposedEmail","summary":"Record human review status for a completed artifact","security":[{"bearerAuth":[]},{"cookieSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","reviewStatus"],"properties":{"id":{"type":"string","format":"uuid"},"reviewStatus":{"type":"string","enum":["pending","passed","failed"]}}}}}},"responses":{"200":{"description":"Updated artifact and review receipt"},"400":{"description":"Invalid review status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Invalid API key or session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/render":{"post":{"operationId":"renderReferenceEmail","summary":"Render original HTML from a reference profile","security":[{"bearerAuth":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["templateId","brandName","subject","headline","body","ctaLabel","ctaUrl"],"properties":{"templateId":{"type":"string"},"brandName":{"type":"string","maxLength":5000},"subject":{"type":"string","maxLength":180},"preheader":{"type":"string","maxLength":180},"headline":{"type":"string","maxLength":240},"body":{"type":"string","maxLength":5000},"ctaLabel":{"type":"string","maxLength":80},"ctaUrl":{"type":"string","format":"uri","pattern":"^https://"},"logoUrl":{"type":"string","format":"uri","pattern":"^https://"},"heroImageUrl":{"type":"string","format":"uri","pattern":"^https://"},"referenceMode":{"type":"string","enum":["full","visual-only","tone-only"],"default":"full","description":"Full applies reviewed design and returns writing guidance; supplied copy is preserved, not rewritten. Metadata-only templates use a labeled generic fallback."},"accentColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}}}}}},"responses":{"200":{"description":"Rendered HTML and plain-text fallback"},"400":{"description":"Render validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Template unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Quota exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/send":{"post":{"operationId":"sendReviewedDraftToVerifiedEmail","summary":"Send a reviewed draft to the verified account email","description":"Session-only safety boundary. The recipient may be omitted and is resolved from the verified session; arbitrary public relay and bearer-key sending are rejected. The HTML hash must match the submitted HTML and an Idempotency-Key is required.","security":[{"cookieSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["html","htmlSha256","subject","brandName"],"properties":{"html":{"type":"string","maxLength":524288},"htmlSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"subject":{"type":"string","maxLength":180},"brandName":{"type":"string","maxLength":80},"to":{"type":"string","format":"email","description":"Optional; must resolve to the verified account email."}}}}}},"responses":{"200":{"description":"Provider accepted the reviewed draft"},"400":{"description":"Invalid or mismatched HTML","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Verified session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Origin, recipient, or consent denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Sending disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"409":{"description":"Idempotency conflict or request in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"502":{"description":"Mail provider rejected the draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/sponsor-opportunities":{"post":{"operationId":"findSponsorOpportunities","summary":"Find reviewed sponsor opportunities","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["domain"],"properties":{"domain":{"type":"string","minLength":1,"maxLength":253},"category":{"type":"string","maxLength":80},"geography":{"type":"string","maxLength":80},"dateFrom":{"type":"string","format":"date-time"},"dateTo":{"type":"string","format":"date-time"},"limit":{"type":"integer","minimum":1,"maximum":5,"default":5}}}}}},"responses":{"200":{"description":"Reviewed opportunities","headers":{"X-Request-Id":{"schema":{"type":"string","format":"uuid"}},"X-Quota-Limit":{"schema":{"type":"integer"}},"X-Quota-Remaining":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SponsorOpportunity"}},"meta":{"type":"object","required":["requestId","count","evidencePolicy","noEstimates"],"properties":{"requestId":{"type":"string","format":"uuid"},"count":{"type":"integer","minimum":0},"evidencePolicy":{"const":"approved_published_only"},"noEstimates":{"const":true}}}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Pilot inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit or quota exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Query unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/placements/{placementId}":{"get":{"operationId":"getSponsorPlacement","summary":"Get one approved placement","security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"placementId","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Reviewed placement evidence"},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"403":{"description":"Pilot inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"404":{"description":"Placement unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"429":{"description":"Rate limit or quota exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"500":{"description":"Query unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}}}}},"/api/v1/platforms/coverage":{"get":{"operationId":"getPlatformCoverage","summary":"Get aggregate public platform coverage","responses":{"200":{"description":"Platform coverage and freshness","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PlatformCoverage"}},"meta":{"type":"object","required":["publicOnly","generatedAt"],"properties":{"publicOnly":{"const":true},"generatedAt":{"type":"string","format":"date-time"}}}}}}}}}}}}}