{"openapi":"3.0.0","info":{"version":"1.0.0","title":"API"},"servers":[{"url":"https://api2.sesamy.com","description":"Current environment"}],"security":[{"OpenID":["openid","email","profile","entitlements"]}],"components":{"securitySchemes":{"OpenID":{"type":"openIdConnect","openIdConnectUrl":"https://token.sesamy.com/.well-known/openid-configuration"},"Basic":{"type":"http","scheme":"basic"}},"schemas":{"Entitlement":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"sku":{"type":"string"},"purchaseOption":{"type":"string"},"cover":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"presentationUrl":{"type":"string"},"publisherContentId":{"type":"string"},"type":{"$ref":"#/components/schemas/EntitlementType"},"origin":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["EXTERNAL"]},"id":{"type":"string"},"listId":{"type":"string"},"name":{"type":"string"}},"required":["type","id"]},{"type":"object","properties":{"type":{"type":"string","enum":["PAYMENTS"]},"contractId":{"type":"string"}},"required":["type"]},{"$ref":"#/components/schemas/EntitlementLicenseOrigin"}]},"hasAccess":{"type":"boolean"},"isPaused":{"type":"boolean","description":"Whether the entitlement is currently paused. Paused entitlements grant no access."},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","sku","title","type","hasAccess","createdAt","updatedAt"]},"EntitlementType":{"type":"string","enum":["article","audiobook","ebook","bundle","podcast","pass","publication","physical_issue"]},"EntitlementLicenseOrigin":{"type":"object","properties":{"type":{"type":"string","enum":["LICENSE"]},"licenseId":{"type":"string","description":"The Vault license the seat is held on. Omitted for a bundle sub-entitlement"},"contractId":{"type":"string","description":"The multi-seat contract the license belongs to. Use it with GET /management/contracts/{id}/seats/users. Omitted when Vault does not carry it","example":"M-V1StGXR8_Z5jdHi6B-myT"},"role":{"type":"string","enum":["owner","member"],"description":"owner administers the seats, member holds one"}},"required":["type"]},"Paywall":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the paywall","example":"aM8o7LqpkGZJ-szyPwe_E"},"vendorId":{"type":"string","description":"Vendor identifier","example":"acme"},"currency":{"type":"string","description":"Currency code for pricing","example":"SEK"},"version":{"type":"number","description":"Paywall version number","example":2},"settings":{"type":"object","properties":{"template":{"type":"string","description":"Paywall template type. Known values: LOGIN for authentication-only, BOXES for subscription options, ARTICLE for single-article purchase. Treat unknown values as unsupported rather than as errors.","example":"BOXES"},"useDefaultLogo":{"type":"boolean","description":"Whether to use the default vendor logo","example":true},"useDefaultCurrency":{"type":"boolean","description":"Whether to use the default vendor currency","example":true},"useDefaultColor":{"type":"boolean","description":"Whether to use the default vendor color","example":true},"styling":{"type":"object","properties":{"dropShadow":{"type":"boolean","description":"Whether to show drop shadow on paywall elements","example":true},"backgroundColor":{"type":"string","description":"Background color in hex format","example":"#000000"},"showBackground":{"type":"boolean","description":"Whether to show the background","example":false}},"required":["dropShadow","backgroundColor","showBackground"]},"displayOptions":{"type":"object","properties":{"enableGift":{"type":"boolean"},"enableCompany":{"type":"boolean"},"enableLoginButton":{"type":"boolean"}}},"loginFields":{"type":"object","properties":{"name":{"type":"boolean","description":"Whether the login form collects the visitor name","example":true}},"description":"Which extra fields the login template collects"},"leaky":{"$ref":"#/components/schemas/LeakySettings"},"redirectUrl":{"type":"string","description":"Paywall-wide URL the visitor is sent to after completing a purchase. Used for subscriptions that do not set their own `redirectUrl`.","example":"https://acme.example.com/welcome"},"redirectLabel":{"type":"string","description":"Paywall-wide label for the button that takes the visitor back to the publisher, shown on the checkout confirmation page and in the order confirmation email. Used for subscriptions that do not set their own `redirectLabel`.","example":"Go to ACME"},"showPricesExVat":{"type":"boolean","description":"Whether prices are displayed excluding VAT","example":false}}},"showLoginButton":{"type":"boolean","description":"Whether to show a login button. When true, indicates a subscription/entitlement paywall. When false with LOGIN template, indicates a login-only paywall.","example":true},"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Subscription identifier","example":"R4gX0YSbSU1WJA7bCrbQw"},"sku":{"type":"string","description":"Product SKU. Omitted for external-link subscriptions.","example":"sid:acme-plus-monthly"},"poId":{"type":"string","description":"Purchase option identifier. Omitted for external-link subscriptions.","example":"VDuH_poxqIPKW638Ok43q"},"title":{"type":"string","description":"Subscription title","example":"ACME Plus monthly"},"description":{"type":"string","description":"Subscription description (rendered from markdown, so it can contain HTML)","example":"<p>Only 720 kr/year - save 20%</p>"},"price":{"type":"number","description":"Regular price","example":99},"discountPrice":{"type":"number","description":"Discounted price if applicable","example":75},"discountCode":{"type":"string","description":"Applied discount code","example":"WELCOME20"},"periodText":{"type":"string","description":"Period rendered next to the headline price, which is `discountPrice` when one is set.","example":"3 months"},"comparePeriodText":{"type":"string","description":"Period rendered next to the struck-through `price` when `discountPrice` is set, for intro offers whose discount covers a different period than the recurring price (99 NOK / 3 months over 199 NOK / month). Renderers fall back to `periodText` when it is omitted.","example":"month"},"tag":{"type":"string","description":"Tag for categorization","example":"Most popular"},"selected":{"type":"boolean","description":"Whether this subscription is pre-selected","example":true},"features":{"type":"array","items":{"type":"string"},"description":"List of features included in this subscription","example":["Daily news","Exclusive interviews"]},"buttonText":{"type":"string","description":"Custom button text","example":"BUY ACCESS"},"readMoreLink":{"type":"string","description":"URL the read more link points at","example":"https://acme.example.com/subscriptions"},"readMoreText":{"type":"string","description":"Read more link text","example":"Read more"},"preferBusiness":{"type":"boolean","description":"Whether this option is preferred for business customers","example":false},"redirectUrl":{"type":"string","description":"URL the visitor is sent to after completing a purchase of this option. Takes precedence over the paywall-wide `settings.redirectUrl`; when both are omitted the renderer falls back to its own component setting.","example":"https://acme.example.com/welcome"},"redirectLabel":{"type":"string","description":"Label for the button that takes the visitor back to the publisher after buying this option, shown on the checkout confirmation page and in the order confirmation email. Takes precedence over the paywall-wide `settings.redirectLabel`; when both are omitted the button reads \"Go to {vendor}\".","example":"Start reading ACME Plus"},"discountId":{"type":"string","description":"Identifier of the discount applied to this option","example":"disc_acme_welcome"},"priceMode":{"type":"string","description":"How the prices of this option are determined: `MANUAL` (fixed prices, the default when omitted) or `AUTOMATIC` (resolved dynamically). Kept as a plain string so a value added upstream later does not fail the whole response.","example":"AUTOMATIC"},"url":{"type":"string","description":"External URL for more information","example":"https://acme.example.com/business"},"pricePeriod":{"type":"object","properties":{"period":{"type":"string","description":"Period unit. Known values: day, week, month, quarter, year.","example":"month"},"time":{"type":"number","description":"Number of period units, an integer of at least 1","example":3}},"required":["period","time"],"description":"Billing period of the recurring `price`","example":{"period":"month","time":1}},"discountPeriod":{"type":"object","properties":{"period":{"type":"string","description":"Period unit. Known values: day, week, month, quarter, year.","example":"month"},"time":{"type":"number","description":"Number of period units, an integer of at least 1","example":3}},"required":["period","time"],"description":"Billing period of the `discountPrice`","example":{"period":"month","time":3}},"discountMonths":{"type":"number","description":"Discount duration in months, when longer than one `discountPeriod`","example":6},"trialDays":{"type":"number","description":"Length of the free trial, in days","example":14}},"required":["selected"]}},"subscriptionsUrl":{"type":"string","description":"URL of the subscription list backing this paywall","example":"https://acme.example.com/subscriptions.json"},"features":{"type":"array","items":{"type":"string"},"description":"General features displayed on the paywall","example":["Everything on acme.example.com"]},"mainColor":{"type":"string","description":"Main brand color in hex format","example":"#3377fe"},"headline":{"type":"string","description":"Paywall headline text","example":"Get access to ACME Plus"},"description":{"type":"string","description":"Paywall description. Authored as markdown and returned as rendered HTML by the render route.","example":"<p>Read every article, on every device.</p>"},"logoUrl":{"type":"string","description":"URL to the vendor logo","example":"https://assets.sesamy.com/vendor-assets/acme/logo.svg"},"footerPaymentMethods":{"type":"array","items":{"type":"string"},"description":"Payment methods displayed in the footer","example":["visa","mastercard","google-pay","apple-pay"]},"singlePurchase":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether single purchase is enabled","example":true},"title":{"type":"string","description":"Single purchase option title","example":"Buy Now"},"description":{"type":"string","description":"Single purchase option description","example":"One-time purchase"},"discountCode":{"type":"string","description":"Applied discount code for single purchase","example":"WELCOME20"},"discountId":{"type":"string","description":"Identifier of the discount applied to the single purchase","example":"disc_acme_welcome"}},"required":["enabled"]},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["id","vendorId","currency","settings","showLoginButton","subscriptions","features"]},"LeakySettings":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the leaky (metered) paywall is enabled","example":true},"count":{"type":"integer","minimum":1,"description":"Number of free articles allowed within the period","example":3},"periodInHours":{"type":"integer","minimum":1,"description":"Length of the metering window, in hours","example":720}},"required":["enabled"]},"StrategyAttribution":{"type":"object","properties":{"source":{"type":"string","description":"UTM source (utm_source)","example":"google"},"medium":{"type":"string","description":"UTM medium (utm_medium)","example":"cpc"},"campaign":{"type":"string","description":"UTM campaign (utm_campaign)","example":"summer_sale"},"term":{"type":"string","description":"UTM term (utm_term)","example":"running shoes"},"content":{"type":"string","description":"UTM content (utm_content)","example":"logolink"},"referrer":{"type":"string","description":"Full referrer URL — parsed server-side into provider/medium","example":"https://www.google.com/"}}},"StrategyContentInfo":{"type":"object","properties":{"contentId":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["article","video","audio","premium"]},"price":{"type":"number"},"currency":{"type":"string"},"publisherId":{"type":"string"},"contentType":{"type":"string","maxLength":100,"description":"schema.org type of the page, e.g. NewsArticle. Targeting only.","example":"NewsArticle"},"section":{"type":"string","maxLength":200,"description":"Site section the content belongs to. Targeting only.","example":"sports"},"tags":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50,"description":"Tags and keywords from the page. Targeting only.","example":["football","premier-league"]},"authors":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":20,"description":"Author names. Targeting only.","example":["Jane Doe"]},"publishedAt":{"type":"string","maxLength":64,"description":"Publication time as ISO 8601. Targeting only.","example":"2026-01-15T09:00:00.000Z"}}},"DcaUnlockResponse":{"type":"object","properties":{"keys":{"type":"object","properties":{"contentKeys":{"type":"array","items":{"type":"object","properties":{"contentName":{"type":"string"},"key":{"type":"string"}},"required":["contentName","key"]}}},"required":["contentKeys"],"additionalProperties":{"nullable":true},"description":"Opened content keys, as base64url, for the granted sections"}},"required":["keys"],"additionalProperties":{"nullable":true}},"DcaRefusal":{"type":"object","properties":{"error":{"type":"string","description":"DCA refusal code, e.g. `denied`, `bad_signature`"},"reason":{"type":"string","enum":["entitlement_paused"]},"paywallId":{"type":"string"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["error"]},"Contract":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"name":{"type":"string"},"userId":{"type":"string"},"payer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id"],"description":"Who is billed. Only set when that is someone other than the user."},"createdAt":{"type":"string"},"confirmedAt":{"type":"string"},"updatedAt":{"type":"string"},"price":{"type":"number"},"nextBillAt":{"type":"string","nullable":true},"nextPrice":{"type":"number","nullable":true},"currency":{"type":"string"},"manageUrl":{"type":"string"},"contractDuration":{"type":"string","enum":["RECURRING","RENEWABLE","PERPETUAL"]},"issuesRemaining":{"type":"number"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The contract line. Unique within the contract, even when two lines share a sku; `recurringPrice` entries refer to it as `id`."},"sku":{"type":"string"},"purchaseOptionId":{"type":"string"},"purchaseOptionName":{"type":"string"},"name":{"type":"string"},"cover":{"type":"string"},"productType":{"type":"string","enum":["article","audiobook","ebook","bundle","podcast","pass","publication","physical_issue","license"]},"purchaseType":{"type":"string"},"isMultiseat":{"type":"boolean"},"quantity":{"type":"number","description":"Billed units."},"seats":{"type":"number","description":"Total seats on a multi-seat item. Unset for single-seat items."}},"required":["id","sku","name","productType","isMultiseat","quantity"]}},"status":{"type":"string"},"isActive":{"type":"boolean"},"recurringInterval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"recurringTime":{"type":"number"},"recurringPrice":{"type":"array","items":{"$ref":"#/components/schemas/ContractPrice"},"description":"The price schedule, ordered by `from`: for example a discounted introductory period followed by the full price. Empty for contracts that do not recur."},"willCancelAt":{"type":"string","nullable":true},"cancelRequestedAt":{"type":"string","nullable":true},"canceledAt":{"type":"string","nullable":true,"description":"When the contract was actually canceled. Null until it has ended."},"cancelReason":{"type":"string","nullable":true},"expiresAt":{"type":"string"},"origin":{"type":"object","properties":{"type":{"type":"string","enum":["CHECKOUT","CHECKOUT_LEGACY","MANUAL","IMPORTED","THIRD_PARTY","OFFER"]},"id":{"type":"string","description":"Id of the originating entity, e.g. the checkout id when type is CHECKOUT."}},"required":["type"]},"paymentData":{"type":"object","properties":{"method":{"type":"string"},"description":{"type":"string"},"brand":{"type":"string"},"walletType":{"type":"string"}}},"appliedDiscounts":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"id":{"type":"string"},"status":{"type":"string","enum":["APPLIED","UNAPPLICABLE"]},"startsAt":{"type":"string","description":"When the discount starts applying. Only set for discounts created ad hoc on the contract; unset means it applies from contract start."},"endsAt":{"type":"string","description":"When the discount stops applying. Only set for discounts created ad hoc on the contract. For a discount code the end is recorded on the price instead: read `discount.endsAt` or `recurringPrice`."}},"required":["name","description","id"]}},"discount":{"$ref":"#/components/schemas/ContractDiscount"}},"required":["id","name","userId","createdAt","updatedAt","price","nextBillAt","nextPrice","currency","items","status","isActive","recurringPrice","willCancelAt","cancelRequestedAt","canceledAt","cancelReason","appliedDiscounts","discount"]},"ContractPrice":{"type":"object","properties":{"from":{"type":"string","description":"When this price starts applying."},"to":{"type":"string","nullable":true,"description":"When this price stops applying. Null when it does not end."},"id":{"type":"string","description":"The contract line this price belongs to. Every price of the same line shares it, so it tells the lines of a multi-item contract apart."},"price":{"type":"number","description":"What each bill in this period totals, in `currency`."},"currency":{"type":"string"},"interval":{"type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"intervalCount":{"type":"number","description":"Number of intervals between bills. `{ interval: \"MONTH\", intervalCount: 3 }` bills every 3 months."},"discount":{"$ref":"#/components/schemas/ContractPriceDiscount"}},"required":["from","to","price","discount"]},"ContractPriceDiscount":{"type":"object","nullable":true,"properties":{"amount":{"type":"number","nullable":true,"description":"Amount taken off the price, in the contract currency."},"percentage":{"type":"number","nullable":true,"description":"Share taken off the price, as a percentage."},"fullPrice":{"type":"number","nullable":true,"description":"What the price would be without the discount."},"codes":{"type":"array","items":{"$ref":"#/components/schemas/ContractPriceDiscountCode"},"description":"The discount codes that produced this discount. Only recorded for discounts applied through the current discount system, so it is empty for older discounts."}},"required":["amount","percentage","fullPrice","codes"]},"ContractPriceDiscountCode":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"amount":{"type":"number","nullable":true,"description":"Amount this code takes off the price, in the contract currency. Null when the code changes the price in another way, such as a special introductory tranche."}},"required":["code","amount"]},"ContractDiscount":{"type":"object","nullable":true,"properties":{"endsAt":{"type":"string","nullable":true,"description":"When the discounted price stops applying and `fullPrice` takes over. Null for a discount that does not lapse."},"amount":{"type":"number","nullable":true,"description":"Amount taken off the next bill, in the contract currency."},"percentage":{"type":"number","nullable":true,"description":"Share taken off the next bill, as a percentage."},"fullPrice":{"type":"number","nullable":true,"description":"What the next bill would total without the discount."}},"required":["endsAt","amount","percentage","fullPrice"]},"UpgradeOption":{"type":"object","properties":{"itemId":{"type":"string","description":"The contract item these paths apply to"},"sku":{"type":"string","description":"The current product of the contract item"},"purchaseOptionId":{"type":"string","description":"The current purchase option of the contract item"},"paths":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["UPGRADE","DOWNGRADE","EQUIVALENT"],"description":"How the target relates to the current purchase option"},"sku":{"type":"string","description":"The product the contract item can change to"},"purchaseOptionId":{"type":"string","description":"The purchase option on the target product, if a specific one applies"},"title":{"type":"string","description":"Display name of the target product or purchase option"},"cover":{"type":"string","description":"Cover image URL of the target product"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}}},"required":["type","sku"]},"description":"The products and purchase options this item can change to"}},"required":["itemId","sku","purchaseOptionId","paths"]},"Amendment":{"type":"object","properties":{"id":{"type":"string"},"contractId":{"type":"string"},"status":{"type":"string","description":"`PENDING` until confirmed, then `CONFIRMED`, or `SCHEDULED` when it applies later. New values may be added."},"appliedDiscounts":{"type":"array","items":{"type":"string"},"description":"The ids of the discounts the amendment applies."},"amendmentType":{"type":"string","description":"`DISCOUNT` for a discount code, `ITEMS` for a plan change. New values may be added."},"nextBill":{"type":"object","properties":{"total":{"type":"number"},"currency":{"type":"string"},"date":{"type":"string"}},"required":["total","currency"],"deprecated":true,"description":"Deprecated: `total` is in minor units. Use `nextPrice`, `currency` and `nextBillAt`."},"nextBillAt":{"type":"string","nullable":true,"format":"date-time","description":"When the contract bills next after the amendment. Null when it does not bill again."},"nextPrice":{"type":"number","nullable":true,"description":"What the next bill totals after the amendment, including tax, in major units of `currency`."},"currency":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/AmendmentItem"},"description":"The contract's items after the amendment. Set for plan changes."},"proration":{"$ref":"#/components/schemas/AmendmentProration"}},"required":["id","contractId","status","appliedDiscounts","amendmentType","nextBillAt","nextPrice","currency","proration"]},"AmendmentItem":{"type":"object","properties":{"id":{"type":"string","description":"The contract item.","example":"item_1"},"sku":{"type":"string","example":"sid:acme-plus-yearly"},"purchaseOptionId":{"type":"string","example":"yearly"}},"required":["id","sku","purchaseOptionId"]},"AmendmentProration":{"type":"object","nullable":true,"properties":{"method":{"type":"string","enum":["IGNORE_CHANGES","POSTPONE","NEXT_PAYMENT","UPFRONT","RESTART_PERIOD"],"description":"How the price difference for the rest of the current period is settled. These are all the methods today, but new ones may be added: for a method you do not know, rely on `amount` and `appliesAt`.\n- `IGNORE_CHANGES`: the plan changes at once and the new price applies from the next bill. Nothing is settled.\n- `POSTPONE`: the plan and price change at the next bill. Nothing changes until then.\n- `NEXT_PAYMENT`: the plan changes at once and `amount` is added to the next bill, as a credit when negative.\n- `UPFRONT`: the plan changes at once and `amount` is charged to the saved payment method on confirm. Upgrades only.\n- `RESTART_PERIOD`: the plan changes at once and a new period starts. `amount` (a full period of the new price, less the unused part of the current one) is charged to the saved payment method on confirm."},"amount":{"type":"number","description":"The price difference settled for the rest of the current period, including tax, in major units of `currency`. Positive is charged, negative is credited. 0 when nothing is settled.","example":41.5},"currency":{"type":"string","example":"SEK"},"appliesAt":{"type":"string","format":"date-time","description":"When the change takes effect.","example":"2026-12-01T00:00:00.000Z"}},"required":["method","amount","currency","appliesAt"],"description":"How the price difference is settled. Set for plan changes, null for other amendments."},"CreateAmendmentRequest":{"oneOf":[{"$ref":"#/components/schemas/DiscountAmendmentRequest"},{"$ref":"#/components/schemas/PlanChangeAmendmentRequest"}],"discriminator":{"propertyName":"type","mapping":{"DISCOUNT":"#/components/schemas/DiscountAmendmentRequest","PLAN_CHANGE":"#/components/schemas/PlanChangeAmendmentRequest"}}},"DiscountAmendmentRequest":{"type":"object","properties":{"type":{"type":"string","enum":["DISCOUNT"],"description":"The type of amendment to create"},"discountCode":{"type":"string","description":"The discount code to apply"}},"required":["type","discountCode"]},"PlanChangeAmendmentRequest":{"type":"object","properties":{"type":{"type":"string","enum":["PLAN_CHANGE"]},"itemId":{"type":"string","minLength":1,"description":"The contract item to change, from `GET .../upgrade-options`. Only needed when the contract has more than one item.","example":"item_1"},"sku":{"type":"string","minLength":1,"description":"The product to change to, from the `paths` of `GET .../upgrade-options`.","example":"sid:acme-plus-yearly"},"purchaseOptionId":{"type":"string","minLength":1,"description":"The purchase option to change to.","example":"yearly"}},"required":["type","sku","purchaseOptionId"]},"Bill":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"contractId":{"type":"string","example":"a1b2c3d4e5f6g7h8i9j0"},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"title":{"type":"string"},"purchaseOptionId":{"type":"string"}},"required":["sku","title"]}},"price":{"type":"number"},"currency":{"type":"string"},"receiptUrl":{"type":"string"},"paymentProvider":{"type":"string"},"paymentMethod":{"type":"string"},"status":{"type":"string"},"updatedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","contractId","items","price","receiptUrl","paymentProvider","paymentMethod","status","updatedAt","createdAt"]},"Transaction":{"type":"object","properties":{"id":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"amount":{"type":"number"},"currency":{"type":"string"},"contractId":{"type":"string"},"isRefund":{"type":"boolean"},"userId":{"type":"string"},"billId":{"type":"string"},"updatedAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","amount","contractId","isRefund","userId","billId","updatedAt","createdAt"]},"Subscription":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"cancelAt":{"type":"string","nullable":true},"createdAt":{"type":"string"},"status":{"type":"string"},"product":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"image":{"type":"string","format":"uri"},"optionId":{"type":"string"},"sku":{"type":"string"}},"required":["name","description","image","optionId","sku"]},"totalIssues":{"type":"number"},"remainingIssues":{"type":"number"},"price":{"type":"number"},"nextPrice":{"type":"number"},"nextPaymentAt":{"type":"string"},"hasAccess":{"type":"boolean"},"manageUrl":{"type":"string"},"userId":{"type":"string"}},"required":["id","currency","createdAt","status","product","hasAccess","manageUrl","userId"]},"UserMetadata":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"TallyValue":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}},"Tally":{"type":"object","properties":{"id":{"type":"string"},"value":{"$ref":"#/components/schemas/TallyValue"},"policies":{"type":"object","properties":{"ttl":{"type":"number","description":"Time to live in seconds"},"maxItems":{"type":"number"},"unique":{"type":"boolean"},"overflow":{"type":"string","enum":["fifo","block"]},"ipSessionSharing":{"type":"boolean"}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","value","createdAt","updatedAt"]},"TallyInsert":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"policies":{"type":"object","properties":{"ttl":{"type":"number","description":"Time to live in seconds"},"maxItems":{"type":"number"},"unique":{"type":"boolean"},"overflow":{"type":"string","enum":["fifo","block"]},"ipSessionSharing":{"type":"boolean"}}}},"required":["value"]},"UserFulfillment":{"type":"object","properties":{"status":{"type":"string"},"updatedAt":{"type":"string"},"createdAt":{"type":"string"},"deliversAt":{"type":"string"},"sku":{"type":"string"},"title":{"type":"string"},"id":{"type":"string"},"cover":{"type":"string","format":"uri"},"numericId":{"type":"number"},"deliveryProvider":{"type":"string"},"itemId":{"type":"string"},"copies":{"type":"number"}},"required":["status","updatedAt","createdAt","sku","title","id","numericId","deliveryProvider","itemId","copies"]},"Profile":{"type":"object","properties":{"userId":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"locale":{"type":"string"},"nickname":{"type":"string"},"picture":{"type":"string"},"name":{"type":"string"},"mobilePhone":{"type":"string"},"workPhone":{"type":"string"},"homePhone":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"user_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"}]}},"billingAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"deliveryAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"companyInfo":{"$ref":"#/components/schemas/CompanyInfo"},"company":{"type":"string","description":"Deprecated: use companyInfo.companyName","deprecated":true},"sub":{"type":"string"},"given_name":{"type":"string"},"family_name":{"type":"string"},"phone_number":{"type":"string"}},"required":["userId","createdAt","updatedAt"]},"CompanyInfo":{"type":"object","properties":{"companyName":{"type":"string"},"vatNr":{"type":"string"},"invoiceEmail":{"type":"string"}}},"Product":{"type":"object","properties":{"cover":{"type":"string"},"language":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"sku":{"type":"string"},"title":{"type":"string"},"productType":{"type":"string"},"publisherContentId":{"type":"string"}},"required":["cover","language","createdAt","updatedAt","sku","title","productType"]},"PaymentIssue":{"type":"object","properties":{"contractId":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"nextPaymentAt":{"type":"string"},"manageUrl":{"type":"string"},"status":{"type":"string","enum":["OVERDUE","CARD_EXPIRED","CARD_WILL_EXPIRE"]}},"required":["createdAt","updatedAt","status"]},"Checkout":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"url":{"type":"string"},"purchaseOptionId":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"geoRestrictions":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["ALLOW","BLOCK"]}},"required":["countries","type"]}}}},"address":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"businessAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"email":{"type":"string"},"givenName":{"type":"string"},"familyName":{"type":"string"},"birthDate":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"referralEmail":{"type":"string"},"language":{"type":"string"},"redirectUrl":{"type":"string"},"isBusiness":{"type":"boolean"},"price":{"type":"number"},"currency":{"type":"string"},"anonymousUserId":{"type":"string"},"attribution":{"$ref":"#/components/schemas/Attribution"},"paymentData":{"type":"object","properties":{"provider":{"type":"string"},"method":{"type":"string"}},"required":["provider","method"]},"paymentMethodsFilter":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethods"}},"fieldSettings":{"type":"object","properties":{"name":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"phone":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"birthdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"referral":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}},"giftMode":{"type":"boolean"},"requireAddress":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"checkoutUrl":{"type":"string"},"status":{"type":"string","enum":["PENDING","WAITING_PAYMENT_CONFIRMATION","COMPLETED"]},"type":{"type":"string","enum":["RECURRING","SINGLE"]},"itemsOwned":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"purchaseOptionId":{"type":"string"},"title":{"type":"string"}},"required":["sku","purchaseOptionId","title"]}},"appliedDiscountCodes":{"type":"array","items":{"$ref":"#/components/schemas/AppliedDiscountCodes"}},"availablePaymentMethods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethods"}},"payer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["items","id","checkoutUrl","status","type","itemsOwned","appliedDiscountCodes","availablePaymentMethods","createdAt","updatedAt"]},"Attribution":{"type":"object","properties":{"utmSource":{"type":"string"},"utmMedium":{"type":"string"},"utmCampaign":{"type":"string"},"utmTerm":{"type":"string"},"utmContent":{"type":"string"},"source":{"type":"string","enum":["CHECKOUT","PAYWALL","OTHER"]},"sourceId":{"type":"string"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected the paywall the checkout was started from, as returned on the paywall","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected the paywall the checkout was started from, as returned on the paywall","example":"st_abc123"},"itemSrc":{"type":"string"},"referrer":{"type":"string"},"publisherContentId":{"type":"string"},"_ga":{"type":"string"},"_gid":{"type":"string"},"_fbp":{"type":"string"},"_fbc":{"type":"string"},"_pk_id":{"type":"string"},"gaSessionId":{"type":"string"}}},"PaymentMethods":{"type":"object","properties":{"provider":{"type":"string"},"methods":{"type":"array","items":{"type":"string"}}},"required":["methods"]},"AppliedDiscountCodes":{"type":"object","properties":{"name":{"type":"string"},"id":{"type":"string"},"code":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["APPLIED","UNAPPLICABLE"]}},"required":["code","status"]},"CreateCheckoutRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"url":{"type":"string"},"purchaseOptionId":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"geoRestrictions":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["ALLOW","BLOCK"]}},"required":["countries","type"]}}}},"address":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"businessAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"email":{"type":"string"},"givenName":{"type":"string"},"familyName":{"type":"string"},"birthDate":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"referralEmail":{"type":"string"},"language":{"type":"string"},"redirectUrl":{"type":"string"},"isBusiness":{"type":"boolean"},"price":{"type":"number"},"currency":{"type":"string"},"anonymousUserId":{"type":"string"},"attribution":{"$ref":"#/components/schemas/Attribution"},"paymentData":{"type":"object","properties":{"provider":{"type":"string"},"method":{"type":"string"}},"required":["provider","method"]},"paymentMethodsFilter":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethods"}},"fieldSettings":{"type":"object","properties":{"name":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"phone":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"birthdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"referral":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}},"giftMode":{"type":"boolean"},"requireAddress":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"requestedDiscountCodes":{"type":"array","items":{"type":"string"}},"payerEmail":{"type":"string"},"redirectLabel":{"type":"string","description":"Label for the button that takes the buyer to `redirectUrl`, shown on the checkout confirmation page and in the order confirmation email. Plain text, not translated. Defaults to \"Go to {vendor}\".","example":"Start reading ACME Plus"}},"required":["items","redirectUrl"]},"UpdateCheckoutRequest":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"url":{"type":"string"},"purchaseOptionId":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"geoRestrictions":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["ALLOW","BLOCK"]}},"required":["countries","type"]}}}},"address":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"businessAddress":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}}},"email":{"type":"string"},"givenName":{"type":"string"},"familyName":{"type":"string"},"birthDate":{"type":"string"},"phoneNumber":{"type":"string"},"country":{"type":"string"},"referralEmail":{"type":"string"},"language":{"type":"string"},"redirectUrl":{"type":"string"},"isBusiness":{"type":"boolean"},"price":{"type":"number"},"currency":{"type":"string"},"anonymousUserId":{"type":"string"},"attribution":{"$ref":"#/components/schemas/Attribution"},"paymentData":{"type":"object","properties":{"provider":{"type":"string"},"method":{"type":"string"}},"required":["provider","method"]},"paymentMethodsFilter":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethods"}},"fieldSettings":{"type":"object","properties":{"name":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"phone":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"birthdate":{"type":"object","properties":{"enabled":{"type":"boolean"},"required":{"type":"boolean"}},"required":["enabled"]},"referral":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}},"giftMode":{"type":"boolean"},"requireAddress":{"type":"boolean"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"requestedDiscountCodes":{"type":"array","items":{"type":"string"}},"payerEmail":{"type":"string"}}},"StrategyExecutionResult":{"type":"object","properties":{"paywallId":{"type":"string","description":"The resolved paywall id","example":"pw123456"},"matchedNode":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["paywall"]},"label":{"type":"string"}},"required":["id","type"],"description":"The flow node that resolved the paywall, omitted when the fallback was used"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"},"debug":{"$ref":"#/components/schemas/StrategyExecutionDebugInfo"}},"required":["paywallId","paywall"]},"StrategyExecutionDebugInfo":{"type":"object","properties":{"requesterObject":{"type":"object","additionalProperties":{"nullable":true}},"flow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"target":{"type":"string","enum":["live","draft"]},"fingerprint":{"type":"string"}},"required":["id","name","target"]},"cache":{"type":"object","properties":{"flowHit":{"type":"boolean"},"paywallHit":{"type":"boolean"}},"required":["flowHit","paywallHit"]},"timing":{"type":"object","properties":{"totalMs":{"type":"number"},"flowFetchAndEvaluationMs":{"type":"number"},"paywallFetchMs":{"type":"number"}},"required":["totalMs","flowFetchAndEvaluationMs","paywallFetchMs"]},"trace":{"type":"object","properties":{"path":{"type":"array","items":{"type":"string"}},"edgesTaken":{"type":"array","items":{"type":"string"}},"usedFallback":{"type":"boolean"},"fallbackReason":{"type":"string"}},"required":["path","edgesTaken","usedFallback"]}},"description":"Present only when debug=true was requested"},"StrategyExecutionRequest":{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"content":{"$ref":"#/components/schemas/StrategyContentInfo"},"debugUserAgent":{"type":"string","description":"Debug-only override for the User-Agent the strategy is evaluated against (e.g. to test device-type rules). Honoured only when debug=true; never forwarded to the upstream body."}}},"SupportSessionToken":{"type":"object","properties":{"token":{"type":"string","description":"A signed JWT for authenticating with the support messenger","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}},"required":["token"]},"LicenseKey":{"type":"object","properties":{"key":{"type":"string","description":"The license key to redeem with the external vendor","example":"ACME1-FSEC2-3XY4Z-DEMO5"},"poolId":{"type":"string","description":"The key pool the key was claimed from","example":"pool_8f3k2m"},"claimedAt":{"type":"string","description":"When the key was claimed","example":"2026-07-01T09:30:00.000Z"},"expiresAt":{"type":"string","description":"When the key stops being valid; a new key can be claimed after this","example":"2027-07-01T09:30:00.000Z"},"status":{"type":"string","enum":["active","expired"],"description":"Whether the key is currently valid","example":"active"}},"required":["key","poolId","expiresAt","status"]}},"parameters":{}},"paths":{"/content/has-access":{"post":{"tags":["content"],"summary":"Check content access without recording a read","description":"Returns a boolean. Resolves fixed paywalls and strategies internally. The legacy media type preserves sesamy-js entitlement/boolean/null results during migration. The content-access media type also returns the selected paywall and, when a strategy chose it, the decisionId and strategyId.","security":[{"Basic":[],"OpenID":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"content":{"$ref":"#/components/schemas/StrategyContentInfo"},"accessLevel":{"type":"string","enum":["public","logged-in","entitlement"]},"publisherContentId":{"type":"string"},"url":{"type":"string","format":"uri"},"paywall":{"type":"string"},"passes":{"type":"array","items":{"type":"string"}}},"required":["publisherContentId","url"]}}}},"responses":{"200":{"description":"Non-consuming access decision","content":{"application/json":{"schema":{"type":"boolean"}},"application/vnd.sesamy.legacy-access+json":{"schema":{"anyOf":[{"type":"boolean"},{"nullable":true},{"$ref":"#/components/schemas/Entitlement"},{"type":"object","properties":{"id":{"type":"string","enum":["leaky-paywall"]},"sku":{"type":"string"},"url":{"type":"string"},"hasAccess":{"type":"boolean","enum":[true]}},"required":["id","sku","url","hasAccess"]}]}},"application/vnd.sesamy.content-access+json":{"schema":{"type":"object","properties":{"hasAccess":{"type":"boolean"},"reason":{"type":"string","enum":["entitlement_paused"]},"result":{"anyOf":[{"type":"boolean"},{"nullable":true},{"$ref":"#/components/schemas/Entitlement"},{"type":"object","properties":{"id":{"type":"string","enum":["leaky-paywall"]},"sku":{"type":"string"},"url":{"type":"string"},"hasAccess":{"type":"boolean","enum":[true]}},"required":["id","sku","url","hasAccess"]}]},"paywallId":{"type":"string"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["hasAccess","result"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/content/unlock":{"post":{"tags":["content"],"summary":"Authorize content delivery and register a successful read","description":"Resolves policies internally. Capsule verifies its signed descriptor before returning keys; proxy grants retain legacy token authorization. Local encoded delivery returns only a decision, never a reusable token or key. DCA delivery answers a publisher-sealed Delegated Content Access request (e.g. Labrador) addressed to issuer \"sesamy\": it verifies the publisher's resourceJWT against the vendor's registered publishers and returns the opened content keys the reader may use.","security":[{"Basic":[],"OpenID":[]}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"content":{"$ref":"#/components/schemas/StrategyContentInfo"},"accessLevel":{"type":"string","enum":["public","logged-in","entitlement"]},"publisherContentId":{"type":"string"},"url":{"type":"string","format":"uri"},"paywall":{"type":"string"},"passes":{"type":"array","items":{"type":"string"}},"delivery":{"type":"string","enum":["encoded","embed","proxy"]}},"required":["publisherContentId","url","delivery"]},{"type":"object","properties":{"resourceJWT":{"type":"string"},"keys":{"type":"array","items":{"type":"object","properties":{"contentName":{"type":"string"},"scope":{"type":"string"},"wrapKeys":{"type":"array","items":{"type":"object","properties":{"kid":{"type":"string"},"key":{"type":"string"}},"required":["kid","key"]},"minItems":1}},"required":["scope","wrapKeys"]},"minItems":1},"shareToken":{"type":"string"},"paywall":{"type":"string","description":"Optional policy reference. Must match data.paywallUrl when a verified policy exists; ignored for legacy resources."},"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"delivery":{"type":"string","enum":["capsule"]},"vendorId":{"type":"string"}},"required":["keys","delivery","vendorId"]},{"type":"object","properties":{"delivery":{"type":"string","enum":["dca"]},"vendorId":{"type":"string"},"request":{"type":"object","additionalProperties":{"nullable":true},"description":"The DCA unlock request the publisher page built for issuer \"sesamy\", unchanged (for Labrador, `labClientAPI.get(\"dca\").request(\"sesamy\").body`)."},"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"shareToken":{"type":"string","maxLength":4096,"description":"A signed link token (`sesamy_token`) the reader arrived with. It opens the article only when it is valid, was signed with the vendor's Capsule key and names this signed article."}},"required":["delivery","vendorId","request"]}]}}}},"responses":{"200":{"description":"Delivery authorization or selected paywall","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["allowed","paywall"]},"reason":{"type":"string","enum":["entitlement_paused"]},"token":{"type":"string"},"paywallId":{"type":"string"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["status"]},{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"contentName":{"type":"string"},"scope":{"type":"string"},"wrapKeys":{"type":"array","items":{"type":"object","properties":{"kid":{"type":"string"},"key":{"type":"string"}},"required":["kid","key"]}}},"required":["scope"]}}},"required":["keys"]},{"$ref":"#/components/schemas/DcaUnlockResponse"}]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Authentication required, or DCA access denied (`error: denied`, with the paywall when one applies)","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},{"$ref":"#/components/schemas/DcaRefusal"}]}}}},"403":{"description":"Capsule authorization denied","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"paywallId":{"type":"string"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts":{"get":{"tags":["contracts"],"summary":"List all contracts","description":"Retrieves all contracts for the current user. Includes subscription plans and one-time purchases with active entitlements.","security":[{"OpenID":[]}],"responses":{"200":{"description":"A list of the user's contracts","content":{"application/json":{"example":[{"id":"1d78271264b9c76d5842911dd70b4353","name":"Premium Subscription","userId":"user123","createdAt":"2023-01-01T12:00:00Z","confirmedAt":"2023-01-01T12:05:00Z","updatedAt":"2023-03-15T09:30:00Z","price":99,"nextBillAt":"2023-04-01T12:00:00Z","willCancelAt":null,"cancelRequestedAt":null,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","sku":"premium-monthly","purchaseOptionId":"monthly","purchaseOptionName":"Monthly plan","name":"Premium Subscription","productType":"pass","isMultiseat":false,"quantity":1}],"status":"ACTIVE","isActive":true,"recurringInterval":"MONTH","recurringTime":1,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts/{contract_id}":{"get":{"tags":["contracts"],"summary":"Get a contract by ID","description":"Retrieves a specific contract by its unique identifier.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"contract_id","in":"path","description":"The unique identifier of the contract"}],"responses":{"200":{"description":"The requested contract","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"1d78271264b9c76d5842911dd70b4353","name":"Premium Subscription","userId":"user123","createdAt":"2023-01-01T12:00:00Z","confirmedAt":"2023-01-01T12:05:00Z","updatedAt":"2023-03-15T09:30:00Z","price":99,"nextBillAt":"2023-04-01T12:00:00Z","willCancelAt":null,"cancelRequestedAt":null,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","sku":"premium-monthly","purchaseOptionId":"monthly","purchaseOptionName":"Monthly plan","name":"Premium Subscription","productType":"pass","isMultiseat":false,"quantity":1}],"status":"ACTIVE","isActive":true,"recurringInterval":"MONTH","recurringTime":1,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts/{contract_id}/upgrade-options":{"get":{"tags":["contracts"],"summary":"List upgrade options","description":"Lists the products and purchase options each item of the contract can be upgraded, downgraded, or switched to. An empty array means the contract cannot be changed.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"contract_id","in":"path","description":"The unique identifier of the contract"}],"responses":{"200":{"description":"The available upgrade and downgrade paths for the contract","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"itemId":"item_1","sku":"sid:acme-plus-monthly","purchaseOptionId":"monthly","paths":[{"type":"UPGRADE","sku":"sid:acme-plus-yearly","purchaseOptionId":"yearly","title":"ACME Plus Yearly","cover":"https://assets.example.com/acme-plus.png"},{"type":"EQUIVALENT","sku":"sid:acme-plus-monthly","purchaseOptionId":"monthly-campaign","title":"ACME Plus Monthly (campaign)"}]}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/UpgradeOption"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts/{contract_id}/cancel":{"post":{"tags":["contracts"],"summary":"Cancel a contract","description":"Cancels a specific contract. For subscriptions, this typically means they will not renew at the end of the current billing period.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"contract_id","in":"path","description":"The unique identifier of the contract"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["TOO_EXPENSIVE","NOT_USING","SWITCHED_COMPETITOR","MISSING_FEATURES","TECHNICAL_ISSUES","DUPLICATE","OTHER"],"description":"Reason for cancellation"},"comment":{"type":"string","description":"Additional feedback about the cancellation"}}}}}},"responses":{"200":{"description":"Contract cancelled successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts/{contract_id}/reactivate":{"post":{"tags":["contracts"],"summary":"Reactivate a contract","description":"Removes a scheduled cancellation, so the contract renews again as before. Only a contract that is still running can be reactivated: one that has already ended has to be bought again. Reactivating a contract that is not set to cancel returns it unchanged.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"contract_id","in":"path","description":"The unique identifier of the contract"}],"responses":{"200":{"description":"The contract, no longer set to cancel","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"1d78271264b9c76d5842911dd70b4353","name":"Premium Subscription","userId":"user123","createdAt":"2023-01-01T12:00:00Z","confirmedAt":"2023-01-01T12:05:00Z","updatedAt":"2023-03-15T09:30:00Z","price":99,"nextBillAt":"2023-04-01T12:00:00Z","willCancelAt":null,"cancelRequestedAt":null,"canceledAt":null,"cancelReason":null,"nextPrice":99,"currency":"SEK","manageUrl":"https://example.com/manage/contract/123","contractDuration":"RECURRING","origin":{"type":"CHECKOUT","id":"chk_1d78271264b9c76d5842911dd70b4353"},"items":[{"id":"line_acme_premium_1","sku":"premium-monthly","purchaseOptionId":"monthly","purchaseOptionName":"Monthly plan","name":"Premium Subscription","productType":"pass","isMultiseat":false,"quantity":1}],"status":"ACTIVE","isActive":true,"recurringInterval":"MONTH","recurringTime":1,"recurringPrice":[{"from":"2023-01-01T12:00:00Z","to":"2023-04-01T12:00:00Z","id":"line_acme_premium_1","price":49.5,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":{"amount":49.5,"percentage":50,"fullPrice":99,"codes":[{"code":"WELCOME50","name":"Welcome offer","amount":49.5}]}},{"from":"2023-04-01T12:00:00Z","to":null,"id":"line_acme_premium_1","price":99,"currency":"SEK","interval":"MONTH","intervalCount":1,"discount":null}],"appliedDiscounts":[{"code":"WELCOME50","name":"Welcome offer","description":"Half price for the first three months","id":"discount_acme_welcome50","status":"APPLIED"}],"discount":null},"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The contract has ended or is in a status that cannot be reactivated","content":{"application/json":{"example":{"message":"A CANCELED contract cannot be reactivated"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts/{contract_id}/amendments":{"post":{"tags":["contracts"],"summary":"Create an amendment","description":"Prepares a change to a contract: `DISCOUNT` applies a discount code, `PLAN_CHANGE` moves the contract to another product or purchase option. The amendment is `PENDING` and changes nothing until it is confirmed with `POST /contracts/{contract_id}/amendments/{amendment_id}/confirm`, so it doubles as a preview: `nextPrice` and `proration` show what the change costs. A plan change must be one of the paths listed by `GET /contracts/{contract_id}/upgrade-options`, and only works on an active recurring contract that is not set to cancel.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"contract_id","in":"path","description":"The unique identifier of the contract"}],"requestBody":{"required":true,"content":{"application/json":{"example":{"type":"DISCOUNT","discountCode":"SUMMER2023"},"schema":{"$ref":"#/components/schemas/CreateAmendmentRequest"}}}},"responses":{"200":{"description":"The created amendment","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"amendment123","contractId":"1d78271264b9c76d5842911dd70b4353","status":"PENDING","appliedDiscounts":[],"amendmentType":"ITEMS","nextBillAt":"2026-12-01T00:00:00.000Z","nextPrice":990,"currency":"SEK","items":[{"id":"item_1","sku":"sid:acme-plus-yearly","purchaseOptionId":"yearly"}],"proration":{"method":"NEXT_PAYMENT","amount":41.5,"currency":"SEK","appliesAt":"2026-11-18T10:00:00.000Z"}},"schema":{"$ref":"#/components/schemas/Amendment"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The plan of the contract cannot be changed in its current state","content":{"application/json":{"example":{"message":"Reactivate the contract before changing its plan"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/contracts/{contract_id}/amendments/{amendment_id}/confirm":{"post":{"tags":["contracts"],"summary":"Confirm an amendment","description":"Confirms a pending amendment for a contract. For a plan change whose `proration.method` is `UPFRONT` or `RESTART_PERIOD`, `proration.amount` is charged to the saved payment method now; a declined payment answers 400. A plan change cannot be confirmed while the contract is set to cancel: reactivate it first.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"contract_id","in":"path","description":"The unique identifier of the contract"},{"schema":{"type":"string","example":"amendment123"},"required":true,"name":"amendment_id","in":"path","description":"The unique identifier of the amendment"}],"responses":{"200":{"description":"Amendment confirmed successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Conflict - The amendment changes the plan of a contract that is set to cancel","content":{"application/json":{"example":{"message":"Reactivate the contract before changing its plan"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/bills":{"get":{"tags":["bills"],"summary":"List all bills","description":"Retrieves all bills for the current user, excluding draft and expired bills. Results are sorted by creation date (newest first).","security":[{"OpenID":[]}],"responses":{"200":{"description":"A list of the user's bills","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"id":"1d78271264b9c76d5842911dd70b4353","contractId":"a1b2c3d4e5f6g7h8i9j0","items":[{"sku":"premium-monthly","title":"Premium Subscription","purchaseOptionId":"monthly"}],"price":99,"currency":"SEK","receiptUrl":"https://example.com/receipts/123","paymentProvider":"stripe","paymentMethod":"card","status":"PAID","updatedAt":"2023-03-01T10:15:00Z","createdAt":"2023-03-01T10:00:00Z"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Bill"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/bills/{id}":{"get":{"tags":["bills"],"summary":"Get a bill by ID","description":"Retrieves a specific bill by its unique identifier.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path","description":"The unique identifier of the bill"}],"responses":{"200":{"description":"The requested bill","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"1d78271264b9c76d5842911dd70b4353","contractId":"a1b2c3d4e5f6g7h8i9j0","items":[{"sku":"premium-monthly","title":"Premium Subscription","purchaseOptionId":"monthly"}],"price":99,"currency":"SEK","receiptUrl":"https://example.com/receipts/123","paymentProvider":"stripe","paymentMethod":"card","status":"PAID","updatedAt":"2023-03-01T10:15:00Z","createdAt":"2023-03-01T10:00:00Z"},"schema":{"$ref":"#/components/schemas/Bill"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/entitlements":{"get":{"tags":["entitlements"],"summary":"List all entitlements","description":"Retrieves all entitlements for the current user with optional filtering by type, SKU, or purchase option ID.","security":[{"OpenID":[]}],"parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/EntitlementType"},{"description":"Filter by entitlement type","example":"article"}]},"required":false,"description":"Filter by entitlement type","name":"type","in":"query"},{"schema":{"type":"string","description":"Filter by SKU","example":"premium-article-123"},"required":false,"description":"Filter by SKU","name":"sku","in":"query"},{"schema":{"type":"string","description":"Filter by purchase option ID","example":"one-time"},"required":false,"description":"Filter by purchase option ID","name":"purchase-option-id","in":"query"},{"schema":{"type":"string","description":"Wait for entitlements created after this timestamp","example":"2023-01-01T00:00:00Z"},"required":false,"description":"Wait for entitlements created after this timestamp","name":"wait-for-entitlement-after","in":"query"}],"responses":{"200":{"description":"A list of the user's entitlements","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"id":"1d78271264b9c76d5842911dd70b4353","sku":"premium-article-123","purchaseOption":"one-time","cover":"https://example.com/cover.jpg","title":"Premium Article","url":"https://example.com/article/123","presentationUrl":"https://example.com/view/article/123","type":"article","origin":{"type":"PAYMENTS","contractId":"contract123"},"hasAccess":true,"createdAt":"2023-01-15T14:30:00Z","updatedAt":"2023-01-15T14:30:00Z"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/entitlements/{id}":{"get":{"tags":["entitlements"],"summary":"Get an entitlement by ID","description":"Retrieves a specific entitlement by its unique identifier.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path","description":"The unique identifier of the entitlement"}],"responses":{"200":{"description":"The requested entitlement","content":{"application/json":{"example":{"id":"1d78271264b9c76d5842911dd70b4353","sku":"premium-article-123","purchaseOption":"one-time","cover":"https://example.com/cover.jpg","title":"Premium Article","url":"https://example.com/article/123","presentationUrl":"https://example.com/view/article/123","type":"article","origin":{"type":"PAYMENTS","contractId":"contract123"},"hasAccess":true,"createdAt":"2023-01-15T14:30:00Z","updatedAt":"2023-01-15T14:30:00Z"},"schema":{"$ref":"#/components/schemas/Entitlement"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/entitlements/{id}/access":{"get":{"tags":["entitlements"],"summary":"Get access information for an entitlement","description":"Retrieves access information (URL and token) for a specific entitlement. The access type (URL or RSS) is determined based on the entitlement type.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path","description":"The unique identifier of the entitlement"}],"responses":{"200":{"description":"Access information for the entitlement","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"access123","url":"https://example.com/access/article/123","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"token":{"type":"string"},"title":{"type":"string"},"filename":{"type":"string"},"type":{"type":"string"}},"required":["id","url"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/transactions":{"get":{"tags":["transactions"],"summary":"List transactions","description":"Retrieves all transactions for the current user, with optional filtering by search query.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Search query to filter transactions","example":"premium"},"required":false,"description":"Search query to filter transactions","name":"q","in":"query"}],"responses":{"200":{"description":"A list of the user's transactions","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"id":"tr_123456789","amount":99,"currency":"SEK","contractId":"contract123","isRefund":false,"userId":"user123","billId":"bill123","updatedAt":"2023-03-01T10:00:00Z","createdAt":"2023-03-01T10:00:00Z"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/subscriptions":{"get":{"tags":["subscriptions"],"summary":"List subscriptions","description":"Retrieves all subscriptions for the current user. This includes both active and canceled subscriptions.","security":[{"OpenID":[]}],"responses":{"200":{"description":"A list of the user's subscriptions","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"id":"1d78271264b9c76d5842911dd70b4353","currency":"SEK","createdAt":"2023-01-01T12:00:00Z","status":"active","product":{"name":"Premium Magazine","description":"Monthly subscription to Premium Magazine","image":"https://example.com/magazine/premium.jpg","optionId":"monthly","sku":"magazine-premium"},"totalIssues":12,"remainingIssues":9,"price":99,"nextPrice":99,"nextPaymentAt":"2023-04-01T12:00:00Z","hasAccess":true,"manageUrl":"https://checkout.sesamy.com/manage/1d78271264b9c76d5842911dd70b4353","userId":"user123"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/subscriptions/{id}":{"get":{"tags":["subscriptions"],"summary":"Get a subscription by ID","description":"Retrieves a specific subscription by its unique identifier.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"1d78271264b9c76d5842911dd70b4353"},"required":true,"name":"id","in":"path","description":"The unique identifier of the subscription"}],"responses":{"200":{"description":"The requested subscription","content":{"application/json":{"example":{"id":"1d78271264b9c76d5842911dd70b4353","currency":"SEK","createdAt":"2023-01-01T12:00:00Z","status":"active","product":{"name":"Premium Magazine","description":"Monthly subscription to Premium Magazine","image":"https://example.com/magazine/premium.jpg","optionId":"monthly","sku":"magazine-premium"},"totalIssues":12,"remainingIssues":9,"price":99,"nextPrice":99,"nextPaymentAt":"2023-04-01T12:00:00Z","hasAccess":true,"manageUrl":"https://checkout.sesamy.com/manage/1d78271264b9c76d5842911dd70b4353","userId":"user123"},"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/user-metadata":{"get":{"tags":["user-metadata"],"summary":"Get all user metadata","description":"Retrieves all metadata entries for the current user.","security":[{"OpenID":[]}],"responses":{"200":{"description":"Object with metadata key-value pairs","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"preferences":"dark-mode","last_visited":"2023-04-01T12:30:00Z","favorite_categories":"news,business,tech"},"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/UserMetadata"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/user-metadata/{id}":{"put":{"tags":["user-metadata"],"summary":"Set user metadata value","description":"Sets a metadata value for the current user with the specified key.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"preferences"},"required":true,"name":"id","in":"path","description":"The key of the metadata entry"}],"requestBody":{"content":{"text/plain":{"example":"dark-mode","schema":{"$ref":"#/components/schemas/UserMetadata"}}}},"responses":{"200":{"description":"Metadata value set successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["user-metadata"],"summary":"Delete user metadata value","description":"Deletes a metadata value for the current user with the specified key.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"preferences"},"required":true,"name":"id","in":"path","description":"The key of the metadata entry"}],"responses":{"200":{"description":"Metadata value deleted successfully","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/tallies":{"get":{"tags":["tallies"],"summary":"List all tallies","description":"Retrieve all tallies for the authenticated user.","security":[{"Basic":[],"OpenID":[]}],"responses":{"200":{"description":"A record of tallies where keys are tally IDs and values are the tally values","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"article_views":["article1","article2"],"product_views":[5,10,15],"login_count":[3]},"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TallyValue"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/tallies/{id}":{"get":{"tags":["tallies"],"summary":"Get a tally by ID","description":"Retrieve a specific tally by its ID for the authenticated user.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"test"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The tally value for the specified ID","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":["article1","article2","article3"],"schema":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"put":{"tags":["tallies"],"summary":"Update a tally","description":"Set a tally to a new value for the authenticated user.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"test"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"anyOf":[{"type":"string"},{"type":"number"}]},"policies":{"type":"object","properties":{"ttl":{"type":"number","description":"Time to live in seconds"},"maxItems":{"type":"number"},"unique":{"type":"boolean"},"overflow":{"type":"string","enum":["fifo","block"]},"ipSessionSharing":{"type":"boolean"}}}},"required":["value"]}}}},"responses":{"200":{"description":"The updated tally object","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"value":["article123"],"id":"article_views","createdAt":"2023-01-01T12:00:00Z","updatedAt":"2023-03-15T09:30:00Z"},"schema":{"$ref":"#/components/schemas/Tally"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/tallies/{id}/push":{"post":{"tags":["tallies"],"summary":"Push value to tally","description":"Add a new value to an existing tally list for the authenticated user.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"test"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TallyInsert"}}}},"responses":{"200":{"description":"The updated tally value after pushing the new value","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":["article1","article2","article123"],"schema":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/fulfillments":{"get":{"tags":["fulfillments"],"summary":"List fulfillments","description":"Retrieves all fulfillments for a specific SKU. Useful for tracking delivery status of physical items.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"The SKU of the publication which can be found by querying the entitlements of type bundle","example":"magazine-april-2023"},"required":true,"description":"The SKU of the publication which can be found by querying the entitlements of type bundle","name":"sku","in":"query"}],"responses":{"200":{"description":"A list of user's fulfillments for the requested SKU","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"id":"fulfillment123","status":"DELIVERED","updatedAt":"2023-04-10T15:20:00Z","createdAt":"2023-04-10T15:00:00Z","deliversAt":"2023-04-15T10:00:00Z","sku":"magazine-april","title":"April Edition","cover":"https://example.com/magazine/april.jpg","numericId":123,"deliveryProvider":"postnord","itemId":"item123","copies":1}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserFulfillment"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/fulfillments/{id}/request-delivery":{"post":{"tags":["fulfillments"],"summary":"Request delivery for a fulfillment item","description":"Request a new delivery for a specific fulfillment item by ID and SKU.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"item123"},"required":true,"name":"id","in":"path","description":"The fulfillment item ID"}],"requestBody":{"content":{"application/json":{"example":{"sku":"magazine-april-2023"},"schema":{"type":"object","properties":{"sku":{"type":"string","description":"The SKU of the item to request delivery for","example":"magazine-april-2023"}},"required":["sku"]}}}},"responses":{"200":{"description":"Delivery request result","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"ok":true},"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/tags":{"get":{"tags":["tags"],"summary":"List user tags","description":"Retrieve all tags associated with the authenticated user.","security":[{"OpenID":[]}],"responses":{"200":{"description":"Array of user tags","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":["premium","subscriber","newsletter"],"schema":{"type":"array","items":{"type":"string"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"post":{"tags":["tags"],"summary":"Add a tag","description":"Add a new tag to the authenticated user.","security":[{"OpenID":[]}],"requestBody":{"content":{"text/plain":{"schema":{"type":"string","description":"The tag value to add","example":"premium"}}}},"responses":{"200":{"description":"Confirmation that the tag was added","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":"OK","schema":{"type":"string"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/tags/{tag}":{"delete":{"tags":["tags"],"summary":"Delete a tag","description":"Remove a tag from the authenticated user.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Tag value to delete","example":"premium"},"required":true,"description":"Tag value to delete","name":"tag","in":"path"}],"responses":{"200":{"description":"Confirmation that the tag was deleted","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":"OK","schema":{"type":"string"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/profile":{"get":{"tags":["profile"],"summary":"Get user profile","description":"Retrieves the authenticated user's profile information.","security":[{"OpenID":[]}],"responses":{"200":{"description":"The user's profile information","content":{"application/json":{"example":{"userId":"user123","firstName":"John","lastName":"Doe","email":"john.doe@example.com","emailVerified":true,"nickname":"Johnny","picture":"https://example.com/profile.jpg","name":"John Doe","mobilePhone":"+1234567890","workPhone":"+1234567891","homePhone":"+1234567892","tags":["premium","subscriber"],"billingAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"deliveryAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"user_metadata":{"preferences":"dark-mode","favorite_categories":"news,business,tech"},"companyInfo":{"companyName":"Acme AB","vatNr":"SE556677889901","invoiceEmail":"invoices@acme.example"},"createdAt":"2023-01-01T12:00:00Z","updatedAt":"2023-03-15T09:30:00Z"},"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"patch":{"tags":["profile"],"summary":"Update user profile","description":"Updates the authenticated user's profile information with the provided data.","security":[{"OpenID":[]}],"requestBody":{"content":{"application/json":{"example":{"firstName":"Jane","lastName":"Smith","nickname":"Janie","mobilePhone":"+9876543210","billingAddress":{"country":"NO","zip":"0150","city":"Oslo","street":"New Street 456"},"user_metadata":{"theme":"dark","preferred_language":"en"},"companyInfo":{"companyName":"Acme AB","vatNr":"SE556677889901","invoiceEmail":"invoices@acme.example"}},"schema":{"type":"object","properties":{"firstName":{"type":"string","nullable":true,"description":"First name of the user","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the user","example":"Doe"},"nickname":{"type":"string","nullable":true,"description":"Nickname of the user","example":"Johnny"},"mobilePhone":{"type":"string","nullable":true,"description":"Mobile phone number","example":"+1234567890"},"workPhone":{"type":"string","nullable":true,"description":"Work phone number","example":"+1234567891"},"homePhone":{"type":"string","nullable":true,"description":"Home phone number","example":"+1234567892"},"billingAddress":{"type":"object","nullable":true,"properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string","minLength":1,"description":"City. Required when setting an address.","example":"Stockholm"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}},"required":["city"],"description":"Billing address information"},"deliveryAddress":{"type":"object","nullable":true,"properties":{"country":{"type":"string","minLength":2,"maxLength":2},"zip":{"type":"string"},"city":{"type":"string","minLength":1,"description":"City. Required when setting an address.","example":"Stockholm"},"street":{"type":"string"},"co":{"type":"string"},"lastName":{"type":"string"},"firstName":{"type":"string"}},"required":["city"],"description":"Delivery address information"},"user_metadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"nullable":true}]},"description":"User metadata key-value pairs. Set a value to null to delete that key."},"companyInfo":{"type":"object","nullable":true,"properties":{"companyName":{"type":"string"},"vatNr":{"type":"string"},"invoiceEmail":{"type":"string"}},"description":"Company / business details for invoicing"},"given_name":{"type":"string","description":"Deprecated: Use firstName instead","deprecated":true},"family_name":{"type":"string","description":"Deprecated: Use lastName instead","deprecated":true},"phone_number":{"type":"string","nullable":true,"description":"Deprecated: Use mobilePhone instead","deprecated":true}}}}}},"responses":{"200":{"description":"The updated user profile","content":{"application/json":{"example":{"userId":"user123","firstName":"John","lastName":"Doe","email":"john.doe@example.com","emailVerified":true,"nickname":"Johnny","picture":"https://example.com/profile.jpg","name":"John Doe","mobilePhone":"+1234567890","workPhone":"+1234567891","homePhone":"+1234567892","tags":["premium","subscriber"],"billingAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"deliveryAddress":{"country":"SE","zip":"12345","city":"Stockholm","street":"Main Street 123","firstName":"John","lastName":"Doe"},"user_metadata":{"preferences":"dark-mode","favorite_categories":"news,business,tech"},"companyInfo":{"companyName":"Acme AB","vatNr":"SE556677889901","invoiceEmail":"invoices@acme.example"},"createdAt":"2023-01-01T12:00:00Z","updatedAt":"2023-03-15T09:30:00Z"},"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"delete":{"tags":["profile"],"summary":"Delete own profile","description":"Allows the authenticated user to delete their own account. This action is irreversible.","security":[{"OpenID":[]}],"responses":{"200":{"description":"Profile deleted successfully","content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/profile/spotify-link":{"get":{"tags":["profile"],"summary":"Check Spotify link status","description":"Checks if the user has connected their Spotify account.","security":[{"OpenID":[]}],"responses":{"200":{"description":"Spotify link status","content":{"application/json":{"example":{"isSpotifyLinked":true},"schema":{"type":"object","properties":{"isSpotifyLinked":{"type":"boolean"}},"required":["isSpotifyLinked"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/profile/unlink-spotify":{"post":{"tags":["profile"],"summary":"Unlink Spotify account","description":"Unlinks the user's connected Spotify account from their profile.","security":[{"OpenID":[]}],"responses":{"200":{"description":"Spotify account unlinked successfully","content":{"application/json":{"example":{"success":true},"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/products/{sku}":{"get":{"tags":["products"],"summary":"Get a product by SKU","description":"Retrieves a specific product by its unique SKU identifier.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"sid:PRVc_h8FIgR2ntoZh9SNu"},"required":true,"name":"sku","in":"path","description":"The unique stock keeping unit (SKU) identifier of the product"}],"responses":{"200":{"description":"The requested product","content":{"application/json":{"example":{"cover":"https://example.com/product/cover.jpg","language":"en","createdAt":"2023-01-15T08:00:00Z","updatedAt":"2023-03-20T14:30:00Z","sku":"sid:PRVc_h8FIgR2ntoZh9SNu","title":"Premium Subscription","productType":"subscription","publisherContentId":"pub-123"},"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/products/{sku}/auto-onboard":{"post":{"tags":["products"],"summary":"Auto-onboard a product","description":"Triggers the auto-onboarding process for a product. This typically grants additional entitlements based on external systems when supported by the product.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"sid:PRVc_h8FIgR2ntoZh9SNu"},"required":true,"name":"sku","in":"path","description":"The unique stock keeping unit (SKU) identifier of the product"}],"responses":{"200":{"description":"The entitlements returned from the auto-onboard process","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"id":"1d78271264b9c76d5842911dd70b4353","sku":"premium-article-123","purchaseOption":"one-time","cover":"https://example.com/cover.jpg","title":"Premium Article","url":"https://example.com/article/123","presentationUrl":"https://example.com/view/article/123","type":"article","origin":{"type":"PAYMENTS","contractId":"contract123"},"hasAccess":true,"createdAt":"2023-01-15T14:30:00Z","updatedAt":"2023-01-15T14:30:00Z"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/Entitlement"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/payment-issues":{"get":{"tags":["payment-issues"],"summary":"List payment issues","description":"Retrieves all payment issues for the current user. This includes overdue payments and expired payment methods.","security":[{"OpenID":[]}],"responses":{"200":{"description":"A list of the user's payment issues","content":{"application/json":{"example":[{"contractId":"contract123","status":"OVERDUE","nextPaymentAt":"2023-04-15T10:00:00Z","manageUrl":"https://checkout.sesamy.com/manage/contract123","createdAt":"2023-03-15T10:00:00Z","updatedAt":"2023-03-15T10:00:00Z"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentIssue"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/proxy":{"get":{"tags":["content"],"summary":"Proxy content","description":"Proxies content from supported providers, optionally extracting specific elements.","parameters":[{"schema":{"type":"string","description":"The URL of the content to proxy","example":"https://www.example.com/article"},"required":true,"description":"The URL of the content to proxy","name":"url","in":"query"},{"schema":{"type":"string","description":"Optional CSS selector to extract specific element from the page","example":".article-content"},"required":false,"description":"Optional CSS selector to extract specific element from the page","name":"selector","in":"query"},{"schema":{"type":"string","description":"Whether to use cache (set to \"false\" to bypass cache)","example":"true"},"required":false,"description":"Whether to use cache (set to \"false\" to bypass cache)","name":"cache","in":"query"}],"responses":{"200":{"description":"The unlocked content","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/checkouts":{"post":{"tags":["checkouts"],"summary":"Create a checkout","description":"Creates a new checkout session with the specified items and settings.","security":[{"Basic":[],"OpenID":[]}],"requestBody":{"content":{"application/json":{"example":{"items":[{"sku":"premium-monthly","purchaseOptionId":"monthly"}],"language":"en","redirectUrl":"https://example.com/success","redirectLabel":"Start reading ACME Plus","email":"user@example.com","givenName":"John","familyName":"Doe","phoneNumber":"+1234567890","birthDate":"1990-01-15","referralEmail":"referrer@example.com","paymentMethodsFilter":[{"provider":"stripe","methods":["card","swish"]}],"attribution":{"utmSource":"newsletter","utmMedium":"email","utmCampaign":"spring2023","source":"PAYWALL","sourceId":"paywall123"}},"schema":{"$ref":"#/components/schemas/CreateCheckoutRequest"}}}},"responses":{"200":{"description":"The created checkout session","content":{"application/json":{"example":{"id":"checkout123","checkoutUrl":"https://checkout.sesamy.com/checkouts/checkout123","status":"COMPLETED","type":"RECURRING","items":[{"sku":"premium-monthly","purchaseOptionId":"monthly"}],"email":"user@example.com","givenName":"John","familyName":"Doe","phoneNumber":"+1234567890","address":{"firstName":"John","lastName":"Doe","street":"Main Street 123","city":"Stockholm","zip":"12345","country":"SE"},"isBusiness":false,"price":99,"currency":"SEK","itemsOwned":[],"appliedDiscountCodes":[],"availablePaymentMethods":[{"provider":"stripe","methods":["card","swish"]}],"country":"SE","language":"en","redirectUrl":"https://example.com/success","createdAt":"2023-03-15T14:30:00Z","updatedAt":"2023-03-15T14:30:00Z","paymentData":{"provider":"stripe","method":"card"},"fieldSettings":{"name":{"enabled":true,"required":true},"phone":{"enabled":true,"required":false},"birthdate":{"enabled":false,"required":false},"referral":{"enabled":false}}},"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/checkouts/{id}":{"get":{"tags":["checkouts"],"summary":"Get a checkout by ID","description":"Retrieves a specific checkout session by its ID.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"checkout123"},"required":true,"name":"id","in":"path","description":"The unique identifier of the checkout"}],"responses":{"200":{"description":"The requested checkout session","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"checkout123","checkoutUrl":"https://checkout.sesamy.com/checkouts/checkout123","status":"COMPLETED","type":"RECURRING","items":[{"sku":"premium-monthly","purchaseOptionId":"monthly"}],"email":"user@example.com","givenName":"John","familyName":"Doe","phoneNumber":"+1234567890","address":{"firstName":"John","lastName":"Doe","street":"Main Street 123","city":"Stockholm","zip":"12345","country":"SE"},"isBusiness":false,"price":99,"currency":"SEK","itemsOwned":[],"appliedDiscountCodes":[],"availablePaymentMethods":[{"provider":"stripe","methods":["card","swish"]}],"country":"SE","language":"en","redirectUrl":"https://example.com/success","createdAt":"2023-03-15T14:30:00Z","updatedAt":"2023-03-15T14:30:00Z","paymentData":{"provider":"stripe","method":"card"},"fieldSettings":{"name":{"enabled":true,"required":true},"phone":{"enabled":true,"required":false},"birthdate":{"enabled":false,"required":false},"referral":{"enabled":false}}},"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}},"patch":{"tags":["checkouts"],"summary":"Update a checkout","description":"Updates an existing checkout session with new customer information or payment method.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","example":"checkout123"},"required":true,"name":"id","in":"path","description":"The unique identifier of the checkout"}],"requestBody":{"content":{"application/json":{"example":{"email":"updated@example.com","payerEmail":"payer@example.com","givenName":"Jane","familyName":"Smith","phoneNumber":"+0987654321","birthDate":"1985-12-25","referralEmail":"new-referrer@example.com","country":"NO","address":{"street":"New Street 456","city":"Oslo","zip":"0150","country":"NO"},"paymentData":{"provider":"stripe","method":"card"}},"schema":{"$ref":"#/components/schemas/UpdateCheckoutRequest"}}}},"responses":{"200":{"description":"The updated checkout session","content":{"application/json":{"example":{"id":"checkout123","checkoutUrl":"https://checkout.sesamy.com/checkouts/checkout123","status":"COMPLETED","type":"RECURRING","items":[{"sku":"premium-monthly","purchaseOptionId":"monthly"}],"email":"user@example.com","givenName":"John","familyName":"Doe","phoneNumber":"+1234567890","address":{"firstName":"John","lastName":"Doe","street":"Main Street 123","city":"Stockholm","zip":"12345","country":"SE"},"isBusiness":false,"price":99,"currency":"SEK","itemsOwned":[],"appliedDiscountCodes":[],"availablePaymentMethods":[{"provider":"stripe","methods":["card","swish"]}],"country":"SE","language":"en","redirectUrl":"https://example.com/success","createdAt":"2023-03-15T14:30:00Z","updatedAt":"2023-03-15T14:30:00Z","paymentData":{"provider":"stripe","method":"card"},"fieldSettings":{"name":{"enabled":true,"required":true},"phone":{"enabled":true,"required":false},"birthdate":{"enabled":false,"required":false},"referral":{"enabled":false}}},"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/vendor":{"get":{"tags":["vendor"],"summary":"Get vendor settings","description":"Retrieves the current vendor settings and configuration.","security":[{"OpenID":[]}],"responses":{"200":{"description":"The vendor settings and configuration","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"vendor123","name":"Sesamy Publisher","logo":"https://example.com/logo.png"},"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the vendor","example":"vendor123"},"name":{"type":"string","description":"The display name of the vendor","example":"Sesamy Publisher"},"logo":{"type":"string","description":"URL to the vendor logo image","example":"https://example.com/logo.png"}},"required":["id","name"],"additionalProperties":{"nullable":true}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/vendors":{"get":{"tags":["vendor"],"summary":"List the vendors where the user has an account","description":"Get the vendors that have a user account matching the authenticated user's email address.","security":[{"OpenID":[]}],"responses":{"200":{"description":"The vendors with a user account matching the user's email","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"name":"ACME","id":"acme","logo":"https://example.com/logo.png"}],"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The display name of the vendor","example":"ACME"},"id":{"type":"string","description":"Unique identifier for the vendor","example":"acme"},"logo":{"type":"string","description":"URL to the vendor logo image","example":"https://example.com/logo.png"}},"required":["name","id"]}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/paywalls/{paywallId}":{"get":{"tags":["paywalls"],"summary":"Get paywall by ID","description":"Retrieves the rendered paywall configuration and settings for the specified paywall ID. This is the public render shape: it does not carry the admin-only `name`, `status`, `entity`, `createdAt`, `modifiedAt` or `previewUrl` fields. A strategy id (`st_…`) executes the strategy for the visitor and returns the paywall it selected, plus `decisionId` and `strategyId`; the query parameters only apply to strategy ids.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Unique identifier of the paywall","example":"pw123456"},"required":true,"description":"Unique identifier of the paywall","name":"paywallId","in":"path"},{"schema":{"type":"string","description":"Strategy ids only: full referrer URL the visitor arrived from (document.referrer), parsed server-side into provider/medium","example":"https://www.google.com/"},"required":false,"description":"Strategy ids only: full referrer URL the visitor arrived from (document.referrer), parsed server-side into provider/medium","name":"referrer","in":"query"},{"schema":{"type":"string","description":"Strategy ids only: UTM source"},"required":false,"description":"Strategy ids only: UTM source","name":"utm_source","in":"query"},{"schema":{"type":"string","description":"Strategy ids only: UTM medium"},"required":false,"description":"Strategy ids only: UTM medium","name":"utm_medium","in":"query"},{"schema":{"type":"string","description":"Strategy ids only: UTM campaign"},"required":false,"description":"Strategy ids only: UTM campaign","name":"utm_campaign","in":"query"},{"schema":{"type":"string","description":"Strategy ids only: UTM term"},"required":false,"description":"Strategy ids only: UTM term","name":"utm_term","in":"query"},{"schema":{"type":"string","description":"Strategy ids only: UTM content"},"required":false,"description":"Strategy ids only: UTM content","name":"utm_content","in":"query"},{"schema":{"type":"string","description":"Strategy ids only: publisher content id of the article the paywall is shown on","example":"article-2024-01-15-news"},"required":false,"description":"Strategy ids only: publisher content id of the article the paywall is shown on","name":"contentId","in":"query"}],"responses":{"200":{"description":"The paywall information and configuration","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"id":"aM8o7LqpkGZJ-szyPwe_E","vendorId":"acme","currency":"SEK","version":2,"settings":{"template":"BOXES","useDefaultLogo":false,"useDefaultCurrency":true,"useDefaultColor":true,"styling":{"dropShadow":true,"backgroundColor":"#000000","showBackground":false},"loginFields":{"name":true},"redirectUrl":"https://acme.example.com/welcome"},"showLoginButton":true,"subscriptions":[{"id":"R4gX0YSbSU1WJA7bCrbQw","sku":"sid:acme-plus-monthly","poId":"VDuH_poxqIPKW638Ok43q","title":"ACME Plus monthly","description":"<p>Cancel any time</p>","price":199,"discountPrice":99,"discountCode":"WELCOME20","periodText":"3 months","comparePeriodText":"month","tag":"Most popular","selected":true,"buttonText":"BUY ACCESS","readMoreText":"Read more","readMoreLink":"https://acme.example.com/subscriptions","redirectUrl":"https://acme.example.com/welcome/plus","features":["Daily news","Exclusive interviews","No lock-in"],"preferBusiness":false}],"features":["Everything on acme.example.com"],"description":"<p>Read every article, on every device.</p>","mainColor":"#3377fe","footerPaymentMethods":["visa","mastercard","google-pay","apple-pay"]},"schema":{"$ref":"#/components/schemas/Paywall"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/paywalls/strategies/{strategyId}/execute":{"post":{"tags":["paywalls"],"deprecated":true,"summary":"Execute a paywall strategy","description":"Evaluates a paywall strategy by id against the visitor's context and returns the resolved paywall plus which rule matched. The body carries UTM attribution and optional content metadata; device, geo, referral, user and daily/weekly article read counts are supplied server-side. Evaluation never consumes a read. Anonymous — paywalls are evaluated for logged-out visitors.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Unique identifier of the strategy","example":"str_abc123"},"required":true,"description":"Unique identifier of the strategy","name":"strategyId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"When \"true\", include debug info (requester object, cache, timing) in the response","example":"true"},"required":false,"description":"When \"true\", include debug info (requester object, cache, timing) in the response","name":"debug","in":"query"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategyExecutionRequest"}}}},"responses":{"200":{"description":"The resolved paywall and strategy match metadata","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrategyExecutionResult"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/paywalls/strategies/{strategyId}/read":{"post":{"tags":["paywalls"],"deprecated":true,"summary":"Register a strategy read for locally encoded content","description":"Evaluates the strategy and permits signed-in LOGIN or configured leaky access. Records successful reads without returning a signed link or decryption key; this cannot authorize protected content delivery. Checks and denied reads do not count.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"strategyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"content":{"$ref":"#/components/schemas/StrategyContentInfo"},"publisherContentId":{"type":"string","description":"Unique identifier of the content being accessed","example":"article-2024-01-15-news"},"url":{"type":"string","format":"uri","description":"URL of the article being accessed","example":"https://example.com/articles/my-article"}},"required":["publisherContentId","url"]}}}},"responses":{"200":{"description":"Encoded read decision, without an access token","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["allowed","paywall"]},"paywallId":{"type":"string"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["status","paywallId","paywall"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/paywalls/strategies/{strategyId}/access":{"post":{"tags":["paywalls"],"deprecated":true,"summary":"Register a read through a paywall strategy and grant access","description":"Executes the strategy to resolve the paywall for the visitor, then records the read against that paywall's leaky allowance exactly like POST /paywalls/{paywallId}/access. Returns a signed link when granted, or the resolved paywall when blocked. Signed-in readers also have the article counted in their daily/weekly article reads, only when access is granted.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Unique identifier of the strategy","example":"st_abc123"},"required":true,"description":"Unique identifier of the strategy","name":"strategyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"$ref":"#/components/schemas/StrategyAttribution"},"content":{"$ref":"#/components/schemas/StrategyContentInfo"},"publisherContentId":{"type":"string","description":"Unique identifier of the content being accessed","example":"article-2024-01-15-news"},"url":{"type":"string","format":"uri","description":"URL of the article being accessed","example":"https://example.com/articles/my-article"}},"required":["publisherContentId","url"]}}}},"responses":{"200":{"description":"Access result — either allowed with a signed link or blocked with the resolved paywall","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["allowed"],"description":"Access is allowed"},"signedLink":{"type":"string","description":"Signed URL granting temporary access to the article","example":"https://example.com/articles/my-article?sesamy_token=eyJhbGciOiJFZERTQSJ9..."},"remaining":{"type":"number","description":"Number of free articles remaining in the current window","example":2},"paywallId":{"type":"string"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["status","signedLink","remaining","paywallId"]},{"type":"object","properties":{"status":{"type":"string","enum":["paywall"],"description":"Access is blocked — paywall should be shown"},"remaining":{"type":"number","enum":[0],"description":"No free articles remaining"},"paywall":{"$ref":"#/components/schemas/Paywall"},"paywallId":{"type":"string"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["status","remaining","paywall","paywallId"]}]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/paywalls/{paywallId}/access":{"post":{"tags":["paywalls"],"deprecated":true,"summary":"Register a leaky paywall read and grant access","description":"Evaluates the configured leaky allowance. LOGIN grants require the signed content policy on the Capsule unlock endpoint. Returns a signed link when granted, or the paywall when blocked. Successful signed-in grants update article-read buckets. Use POST /access/check to test availability without consuming a read.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Unique identifier of the paywall","example":"pw123456"},"required":true,"description":"Unique identifier of the paywall","name":"paywallId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"publisherContentId":{"type":"string","description":"Unique identifier of the content being accessed","example":"article-2024-01-15-news"},"url":{"type":"string","format":"uri","description":"URL of the article being accessed","example":"https://example.com/articles/my-article"}},"required":["publisherContentId","url"]}}}},"responses":{"200":{"description":"Access check result — either allowed with a signed link or blocked with paywall config","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["allowed"],"description":"Access is allowed"},"signedLink":{"type":"string","description":"Signed URL granting temporary access to the article","example":"https://example.com/articles/my-article?sesamy_token=eyJhbGciOiJFZERTQSJ9..."},"remaining":{"type":"number","description":"Number of free articles remaining in the current window","example":2}},"required":["status","signedLink","remaining"]},{"type":"object","properties":{"status":{"type":"string","enum":["paywall"],"description":"Access is blocked — paywall should be shown"},"remaining":{"type":"number","enum":[0],"description":"No free articles remaining"},"paywall":{"$ref":"#/components/schemas/Paywall"}},"required":["status","remaining","paywall"]}]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/paywalls/{paywallId}/access/check":{"post":{"tags":["paywalls"],"deprecated":true,"summary":"Check leaky paywall availability without consuming a read","description":"Checks the configured leaky allowance without recording a read. Used to advertise availability; call POST /access to actually grant access and record the read.","security":[{"Basic":[],"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"Unique identifier of the paywall","example":"pw123456"},"required":true,"description":"Unique identifier of the paywall","name":"paywallId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"publisherContentId":{"type":"string","description":"Unique identifier of the content being accessed","example":"article-2024-01-15-news"},"url":{"type":"string","format":"uri","description":"URL of the article being accessed","example":"https://example.com/articles/my-article"}},"required":["publisherContentId"]}}}},"responses":{"200":{"description":"Whether leaky access is available, with remaining count","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["allowed","paywall"],"description":"Whether leaky access is currently available without consuming a read","example":"allowed"},"remaining":{"type":"number","description":"Free articles remaining in the current window","example":2},"paywall":{"allOf":[{"$ref":"#/components/schemas/Paywall"},{"description":"Paywall configuration, included when access is blocked"}]}},"required":["status","remaining"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/diagnostics":{"post":{"tags":["diagnostics"],"summary":"Submit user diagnostics","description":"Submit diagnostic data for debugging purposes. Data is stored with user consent and can be retrieved by support staff.","security":[{"Basic":[],"OpenID":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"The authenticated user ID (sub)"},"fallbackId":{"type":"string","description":"A fallback identifier for unauthenticated users"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when diagnostics were collected"},"pageUrl":{"type":"string","description":"The page URL where diagnostics were collected"},"pageTitle":{"type":"string","description":"The page title where diagnostics were collected"},"profile":{"type":"object","additionalProperties":{"nullable":true},"description":"User profile data"},"entitlements":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"User entitlements"},"contracts":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}},"description":"User contracts"},"tags":{"type":"array","items":{"type":"string"},"description":"User tags"},"tallies":{"type":"object","additionalProperties":{"nullable":true},"description":"User tallies"},"browser":{"type":"object","properties":{"userAgent":{"type":"string"},"platform":{"type":"string"},"language":{"type":"string"},"languages":{"type":"array","items":{"type":"string"}},"cookiesEnabled":{"type":"boolean"},"onLine":{"type":"boolean"},"hardwareConcurrency":{"type":"number"},"deviceMemory":{"type":"number"},"maxTouchPoints":{"type":"number"},"vendor":{"type":"string"},"viewportWidth":{"type":"number"},"viewportHeight":{"type":"number"},"screenWidth":{"type":"number"},"screenHeight":{"type":"number"},"pixelRatio":{"type":"number"},"colorDepth":{"type":"number"},"timezone":{"type":"string"},"timezoneOffset":{"type":"number"}},"description":"Browser and device information"},"detection":{"type":"object","properties":{"adBlockEnabled":{"type":"boolean"},"incognitoMode":{"type":"boolean"},"inAppBrowser":{"type":"boolean"}},"description":"Detection results (adblock, incognito, etc.)"},"localStorage":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"redacted":{"type":"boolean"}},"required":["key","value"]},"description":"Sesamy-related localStorage entries"},"sessionStorage":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"},"redacted":{"type":"boolean"}},"required":["key","value"]},"description":"Sesamy-related sessionStorage entries"},"sdkVersion":{"type":"string","description":"Sesamy-js SDK version"},"clientId":{"type":"string","description":"The client ID / vendor ID"},"errors":{"type":"array","items":{"type":"string"},"description":"Errors encountered during diagnostics collection"}},"required":["timestamp"]}}}},"responses":{"201":{"description":"Diagnostics stored successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"id":{"type":"string","description":"The identifier used for storing the diagnostics"},"timestamp":{"type":"string","description":"The timestamp of the stored diagnostics"}},"required":["success","id","timestamp"]}}}},"400":{"description":"Bad Request - Invalid payload or missing identifier","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/capsule/vendors/{vendorId}/.well-known/jwks.json":{"get":{"tags":["capsule"],"summary":"Get JWKS (JSON Web Key Set) for a vendor","description":"Returns the public keys used to verify Capsule token signatures for a specific vendor in JWKS format.","parameters":[{"schema":{"type":"string","example":"varldenom"},"required":true,"name":"vendorId","in":"path","description":"The vendor identifier"}],"responses":{"200":{"description":"JWKS containing public keys for token verification","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Cache control header"}},"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","additionalProperties":{"nullable":true}}}},"required":["keys"]}}}},"404":{"description":"Vendor not found or capsule not configured","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/capsule/vendors/{vendorId}/unlock":{"post":{"tags":["capsule"],"deprecated":true,"summary":"Unlock encrypted content","description":"Unlocks encrypted Capsule content using the DCA unlock request format. Each `keys` entry carries a `scope` identifying the required access tier. Supports authenticated entitlements, pre-signed share tokens, and policies bound in a verified publisher resourceJWT (data.paywallUrl). Policy grants validate the resource scopes and record reads after key generation.","security":[{"OpenID":[]},{}],"parameters":[{"schema":{"type":"string","example":"varldenom"},"required":true,"name":"vendorId","in":"path","description":"The vendor identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"resourceJWT":{"type":"string"},"keys":{"type":"array","items":{"type":"object","properties":{"contentName":{"type":"string"},"scope":{"type":"string"},"wrapKeys":{"type":"array","items":{"type":"object","properties":{"kid":{"type":"string"},"key":{"type":"string"}},"required":["kid","key"]},"minItems":1}},"required":["scope","wrapKeys"]},"minItems":1},"shareToken":{"type":"string"},"paywall":{"type":"string","description":"Optional policy reference. Must match data.paywallUrl when a verified policy exists; ignored for legacy resources."},"attribution":{"$ref":"#/components/schemas/StrategyAttribution"}},"required":["keys"]}}}},"responses":{"200":{"description":"Derived keys for decrypting content","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"keys":[{"scope":"premium","wrapKeys":[{"kid":"260326T10","key":"base64url-encoded-key..."}]}]},"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"contentName":{"type":"string"},"scope":{"type":"string"},"wrapKeys":{"type":"array","items":{"type":"object","properties":{"kid":{"type":"string"},"key":{"type":"string"}},"required":["kid","key"]}}},"required":["scope"]}}},"required":["keys"]}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Access denied, optionally including the selected paywall","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"paywallId":{"type":"string"},"paywall":{"$ref":"#/components/schemas/Paywall"},"decisionId":{"type":"string","description":"Id of the strategy decision that selected this paywall. Pass it as `attribution.decisionId` when creating a checkout from the paywall.","example":"6f1c2a4e-9b7d-4c3a-8e2f-1a5b6c7d8e9f"},"strategyId":{"type":"string","description":"Id of the strategy that selected this paywall. Pass it as `attribution.strategyId` when creating a checkout from the paywall.","example":"st_abc123"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/capsule/vendors/{vendorId}/verify":{"post":{"tags":["capsule"],"summary":"Verify a Capsule signed token","description":"Verifies a Capsule-signed token (from a signed article link or the `signedLink` returned by `paywall.hasAccess`) using the vendor's signing key. Returns the decoded payload when the signature is valid and the token is not expired. No authentication is required — the token itself is the credential.","parameters":[{"schema":{"type":"string","example":"varldenom"},"required":true,"name":"vendorId","in":"path","description":"The vendor identifier"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The signed token to verify (from a signed link or paywall.hasAccess response)"}},"required":["token"]}}}},"responses":{"200":{"description":"Verification result","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Cache control header"}},"content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"message":{"type":"string"},"payload":{"type":"object","properties":{"iss":{"type":"string"},"tier":{"type":"string"},"contentId":{"type":"string"},"tid":{"type":"string"},"iat":{"type":"number"},"exp":{"type":"number"},"url":{"type":"string"},"userId":{"type":"string"},"maxUses":{"type":"number"},"meta":{"type":"object","additionalProperties":{"nullable":true}}},"required":["iss","tier","contentId","tid","iat","exp"]}},"required":["valid"]}}}},"404":{"description":"Vendor not found or capsule not configured","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/auth/:clientId/login":{"get":{"tags":["auth"],"summary":"Initiate login","description":"Initiates the OAuth authorization code flow with PKCE. Redirects to the auth server.","parameters":[{"schema":{"type":"string","description":"OAuth client ID","example":"my-client-id"},"required":true,"description":"OAuth client ID","name":"clientId","in":"path"},{"schema":{"type":"string","description":"URL to redirect to after successful login: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 `INVALID_RETURN_TO`.","example":"https://www.example.com/article"},"required":false,"description":"URL to redirect to after successful login: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 `INVALID_RETURN_TO`.","name":"return_to","in":"query"},{"schema":{"type":"string","description":"The API audience to request","example":"https://api.sesamy.com"},"required":false,"description":"The API audience to request","name":"audience","in":"query"},{"schema":{"type":"string","description":"Space-separated list of scopes","example":"openid profile email offline_access"},"required":false,"description":"Space-separated list of scopes","name":"scope","in":"query"},{"schema":{"type":"string","description":"OIDC prompt parameter forwarded to the auth server. Use \"none\" for a silent authentication attempt (e.g. migrating an existing SSO session) — the callback returns the user anonymously instead of erroring when no session exists.","example":"none"},"required":false,"description":"OIDC prompt parameter forwarded to the auth server. Use \"none\" for a silent authentication attempt (e.g. migrating an existing SSO session) — the callback returns the user anonymously instead of erroring when no session exists.","name":"prompt","in":"query"},{"schema":{"type":"string","description":"Space-separated list of preferred UI locales (BCP 47), forwarded to the auth server to localize the login screens.","example":"sv en"},"required":false,"description":"Space-separated list of preferred UI locales (BCP 47), forwarded to the auth server to localize the login screens.","name":"ui_locales","in":"query"},{"schema":{"type":"string","description":"OIDC login_hint forwarded to the auth server — the email to prefill on the login screen. The user can still authenticate as someone else; this is only a hint.","example":"user@example.com"},"required":false,"description":"OIDC login_hint forwarded to the auth server — the email to prefill on the login screen. The user can still authenticate as someone else; this is only a hint.","name":"login_hint","in":"query"},{"schema":{"type":"string","description":"AuthHero session transfer token forwarded to /authorize, which logs the reader in without a prompt. Comes from the fragment of a `/auth/session-transfer` redirect; use with `prompt=none`. Never stored in the login state."},"required":false,"description":"AuthHero session transfer token forwarded to /authorize, which logs the reader in without a prompt. Comes from the fragment of a `/auth/session-transfer` redirect; use with `prompt=none`. Never stored in the login state.","name":"session_transfer_token","in":"query"},{"schema":{"type":"string","description":"JSON-stringified attribution (UTM tags, referrer, etc.) forwarded as-is to the auth server so it can attribute the signup or login. Dropped if longer than 2048 characters.","example":"{\"utmSource\":\"newsletter\",\"utmCampaign\":\"spring\"}"},"required":false,"description":"JSON-stringified attribution (UTM tags, referrer, etc.) forwarded as-is to the auth server so it can attribute the signup or login. Dropped if longer than 2048 characters.","name":"attribution","in":"query"},{"schema":{"type":"string","description":"Internal: marks an automatic retry triggered by a lost state cookie. Used to prevent infinite login loops."},"required":false,"description":"Internal: marks an automatic retry triggered by a lost state cookie. Used to prevent infinite login loops.","name":"retry","in":"query"}],"responses":{"302":{"description":"Redirect to authorization server","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"400":{"description":"`return_to` is not a relative path or a URL on the same site as the proxy","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_RETURN_TO"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/auth/:clientId/callback":{"get":{"tags":["auth"],"summary":"OAuth callback","description":"Handles the OAuth callback, exchanges code for tokens, and sets cookies.","parameters":[{"schema":{"type":"string","description":"OAuth client ID","example":"my-client-id"},"required":true,"description":"OAuth client ID","name":"clientId","in":"path"},{"schema":{"type":"string","description":"Authorization code from auth server"},"required":false,"description":"Authorization code from auth server","name":"code","in":"query"},{"schema":{"type":"string","description":"State parameter for CSRF protection"},"required":false,"description":"State parameter for CSRF protection","name":"state","in":"query"},{"schema":{"type":"string","description":"Error code if authorization failed"},"required":false,"description":"Error code if authorization failed","name":"error","in":"query"},{"schema":{"type":"string","description":"Human-readable error description"},"required":false,"description":"Human-readable error description","name":"error_description","in":"query"}],"responses":{"302":{"description":"Redirect to return URL or home","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"400":{"description":"Invalid callback parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"500":{"description":"Token exchange failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/auth/logout":{"get":{"tags":["auth"],"summary":"Logout","description":"Clears auth cookies and optionally redirects to auth server logout. Prefer GET /auth/{clientId}/logout so the auth server logout is reached even when the client hint cookie is unavailable.","parameters":[{"schema":{"type":"string","description":"URL to redirect to after logout: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 `INVALID_RETURN_TO` and the session is left as it was.","example":"https://www.example.com"},"required":false,"description":"URL to redirect to after logout: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 `INVALID_RETURN_TO` and the session is left as it was.","name":"return_to","in":"query"},{"schema":{"type":"string","description":"Set to \"true\" to only clear local cookies without redirecting to the auth server. By default the auth server session is also cleared.","example":"true"},"required":false,"description":"Set to \"true\" to only clear local cookies without redirecting to the auth server. By default the auth server session is also cleared.","name":"local_only","in":"query"}],"responses":{"302":{"description":"Redirect after logout","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"400":{"description":"`return_to` is not a relative path or a URL on the same site as the proxy","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_RETURN_TO"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/auth/:clientId/logout":{"get":{"tags":["auth"],"summary":"Logout","description":"Clears auth cookies and, unless local_only is set, redirects through the auth server logout. Mirrors /auth/{clientId}/login: taking the clientId from the path means the auth server logout is reached even when the client hint cookie is missing.","parameters":[{"schema":{"type":"string","description":"OAuth client ID","example":"my-client-id"},"required":true,"description":"OAuth client ID","name":"clientId","in":"path"},{"schema":{"type":"string","description":"URL to redirect to after logout: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 `INVALID_RETURN_TO` and the session is left as it was.","example":"https://www.example.com"},"required":false,"description":"URL to redirect to after logout: a relative path, or a URL on the same site (registrable domain) as the proxy. Anything else is refused with 400 `INVALID_RETURN_TO` and the session is left as it was.","name":"return_to","in":"query"},{"schema":{"type":"string","description":"Set to \"true\" to only clear local cookies without redirecting to the auth server. By default the auth server session is also cleared.","example":"true"},"required":false,"description":"Set to \"true\" to only clear local cookies without redirecting to the auth server. By default the auth server session is also cleared.","name":"local_only","in":"query"}],"responses":{"302":{"description":"Redirect after logout","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"400":{"description":"`return_to` is not a relative path or a URL on the same site as the proxy","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_RETURN_TO"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/auth/userinfo":{"get":{"tags":["auth"],"summary":"Get user info","description":"Returns information about the currently authenticated user from cookies.","responses":{"200":{"description":"User information","content":{"application/json":{"schema":{"type":"object","properties":{"authenticated":{"type":"boolean"},"sub":{"type":"string"},"exp":{"type":"number"},"scope":{"type":"string"}},"required":["authenticated"]}}}}}}},"/auth/{clientId}/session":{"post":{"tags":["auth"],"summary":"Create a cookie session from an access token","description":"Turns a bearer access token the caller already holds into the same HttpOnly cookie session the login callback issues, so cookie-mode (BFF) clients can adopt a token handed to them out of band — a deep link from a native app, an email link, a server-issued token. sesamy-js calls this for a `#access_token=` URL fragment. The token is verified against the token service JWKS before it is stored. No refresh token is involved: the session ends when the access token expires, and any refresh cookie from an earlier login on this browser is dropped so it cannot take over once that happens.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","description":"OAuth client ID (the vendor id). Must match the token's vendor.","example":"acme"},"required":true,"description":"OAuth client ID (the vendor id). Must match the token's vendor.","name":"clientId","in":"path"}],"responses":{"200":{"description":"Session cookies set. Same shape as /auth/userinfo.","content":{"application/json":{"schema":{"type":"object","properties":{"authenticated":{"type":"boolean","enum":[true]},"sub":{"type":"string"},"exp":{"type":"number"},"scope":{"type":"string"}},"required":["authenticated","sub","exp"]}}}},"401":{"description":"No bearer access token in the Authorization header","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"403":{"description":"The token was issued for a different vendor than the path names","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/auth/spotify-link":{"get":{"tags":["auth"],"summary":"Link Spotify (BFF token handoff)","description":"Redirects the browser to the access-sync Spotify callback with the user's access token injected server-side. Used by sesamy-js in cookie/BFF mode, where the access token lives in an HttpOnly cookie and never enters client JS — only this proxy can decrypt it. Unauthenticated requests are bounced through the login flow and returned here afterwards.","parameters":[{"schema":{"type":"string","description":"Product SKU (subscription identifier) to link to Spotify","example":"sid:acme-plus-monthly"},"required":true,"description":"Product SKU (subscription identifier) to link to Spotify","name":"sku","in":"query"}],"responses":{"302":{"description":"Redirect to access-sync, or to login when unauthenticated","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"401":{"description":"Not authenticated and no client hint to start a login flow","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/auth/session-transfer":{"get":{"tags":["auth"],"summary":"Open a Sesamy page logged in (session transfer)","description":"Redirects the browser to a Sesamy page (checkout, account, consume) and logs the reader in there. Used by sesamy-js in cookie/BFF mode for links built with `sessionTransfer: true`. The proxy exchanges the refresh token from the HttpOnly cookie for an AuthHero session transfer token at click time, so the token's 60 seconds start when the reader follows the link. The target receives `#access_token=…&session_transfer_token=…` in the URL fragment. Without a session, or when the exchange fails, the reader is sent on without the session transfer token.","parameters":[{"schema":{"type":"string","format":"uri","description":"Absolute URL of the Sesamy page to open. Must be one of the allowed Sesamy origins.","example":"https://checkout3.sesamy.com/?sku=sid%3Aacme-plus-monthly"},"required":true,"description":"Absolute URL of the Sesamy page to open. Must be one of the allowed Sesamy origins.","name":"target","in":"query"}],"responses":{"302":{"description":"Redirect to the target page","headers":{"Location":{"schema":{"type":"string"},"required":true}}},"400":{"description":"`target` is missing or not a URL (query validation error), or is a URL but not an allowed Sesamy page (`INVALID_TARGET`)","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","enum":["INVALID_TARGET"]},"message":{"type":"string"}},"required":["code","message"]},{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"name":{"type":"string"},"issues":{"type":"array","items":{"nullable":true}}},"required":["name","issues"]}},"required":["success","error"]}]}}}}}}},"/support-session":{"get":{"tags":["support-session"],"summary":"Generate support session token","description":"Generates a short-lived signed JWT for authenticating the current user with the support messenger.","security":[{"OpenID":[]}],"responses":{"200":{"description":"A signed support session token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportSessionToken"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/licenses":{"get":{"tags":["licenses"],"summary":"List the user's license keys","description":"Returns the user's most recently claimed key in the given pool, including expired keys (status=expired) so clients can offer a re-claim. Empty when nothing has been claimed yet. Read-only: never assigns a key.","security":[{"OpenID":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"The license key pool to look in. Publishers get the pool ID when creating the pool","example":"pool_8f3k2m"},"required":true,"description":"The license key pool to look in. Publishers get the pool ID when creating the pool","name":"poolId","in":"query"}],"responses":{"200":{"description":"The user's license keys in the pool","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":[{"key":"ACME1-FSEC2-3XY4Z-DEMO5","poolId":"pool_8f3k2m","claimedAt":"2026-07-01T09:30:00.000Z","expiresAt":"2027-07-01T09:30:00.000Z","status":"active"}],"schema":{"type":"array","items":{"$ref":"#/components/schemas/LicenseKey"}}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}},"/licenses/claim":{"post":{"tags":["licenses"],"summary":"Claim a license key","description":"Claims a key from the pool for the current user. Requires an active entitlement for the SKU configured on the pool. Idempotent: if the user already holds an unexpired key, that key is returned. After a key expires, calling claim again assigns a new one.","security":[{"OpenID":[]}],"requestBody":{"content":{"application/json":{"example":{"poolId":"pool_8f3k2m"},"schema":{"type":"object","properties":{"poolId":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$","description":"The license key pool to claim a key from","example":"pool_8f3k2m"}},"required":["poolId"]}}}},"responses":{"200":{"description":"The claimed license key","headers":{"cache-control":{"schema":{"type":"string"},"required":false},"vary":{"schema":{"type":"string"},"required":false},"Last-Modified":{"schema":{"type":"string"},"required":false},"X-Request-Id":{"schema":{"type":"string"},"required":false}},"content":{"application/json":{"example":{"key":"ACME1-FSEC2-3XY4Z-DEMO5","poolId":"pool_8f3k2m","claimedAt":"2026-07-01T09:30:00.000Z","expiresAt":"2027-07-01T09:30:00.000Z","status":"active"},"schema":{"$ref":"#/components/schemas/LicenseKey"}}}},"400":{"description":"Bad Request - The request failed validation, or an upstream service rejected it. The message says which.","content":{"application/json":{"example":{"message":"Failed to update user profile: Item size has exceeded the maximum allowed size"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Authentication required","content":{"application/json":{"example":{"message":"Unauthorized"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"message":"Forbidden"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"example":{"message":"Not Found"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"The pool has no available keys","content":{"application/json":{"example":{"message":"No license keys available in this pool"},"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"503":{"description":"Service Unavailable - Failed to connect to upstream service"}}}}}}