Superwall Paywall Resolver (Public) API

openapi: 3.2.0
info:
  title: Superwall API V2 Paywall Resolver (Public) API
  version: 2.0.0
  description: Superwall V2 API - Scope-based authentication with organization API keys
servers:
- url: https://api.superwall.com
  description: Production
- url: https://api.superwall.dev
  description: Staging
- url: /
  description: Local
security: []
tags:
- name: Paywall Resolver (Public)
  description: 'Resolve a numeric paywall id to its identifier. Authenticated with a preview capability (sat_ or API-minted pvt_) from the debugger deep link, sent as Authorization: Bearer .'
paths:
  /v2/paywalls/resolve:
    get:
      tags:
      - Paywall Resolver (Public)
      operationId: paywallresolvev2.resolvePaywall
      parameters:
      - name: id
        in: query
        schema:
          type: string
        required: true
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  identifier:
                    type: string
                    description: URL-safe identifier (slug) for the paywall
                  name:
                    type: string
                    description: Display name of the paywall
                  application_id:
                    type: string
                required:
                - id
                - identifier
                - name
                - application_id
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  _tag:
                    type: string
                    enum:
                    - HttpApiDecodeError
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        _tag:
                          type: string
                          enum:
                          - Type
                          - Missing
                          - Unexpected
                          - Forbidden
                          - Pointer
                          - Refinement
                          - Transformation
                          - Composite
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                            - type: object
                              properties:
                                _tag:
                                  type: string
                                  enum:
                                  - symbol
                                key:
                                  type: string
                              required:
                              - _tag
                              - key
                              additionalProperties: false
                        message:
                          type: string
                      required:
                      - _tag
                      - path
                      - message
                      additionalProperties: false
                  message:
                    type: string
                required:
                - _tag
                - issues
                - message
                additionalProperties: false
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  _tag:
                    type: string
                    enum:
                    - '@superwall/api-schema/v2/errors/ResourceNotFound'
                  type:
                    anyOf:
                    - type: string
                      enum:
                      - api_error
                      - authentication_error
                      - invalid_request_error
                      - rate_limit_error
                      - permission_error
                  code:
                    anyOf:
                    - type: string
                      enum:
                      - resource_missing
                      - resource_already_exists
                      - resource_archived
                      - parameter_invalid
                      - parameter_missing
                      - parameter_unknown
                      - invalid_reference
                      - unsupported_operation
                      - idempotency_key_in_use
                      - rate_limit_exceeded
                      - invalid_api_key
                      - invalid_api_key_format
                      - missing_api_key
                      - authentication_failed
                      - invalid_session
                      - organization_required
                      - insufficient_permissions
                      - internal_error
                      - upstream_service_error
                      - side_effect_failed
                  message:
                    anyOf:
                    - type: string
                  param:
                    anyOf:
                    - type: string
                  doc_url:
                    anyOf:
                    - type: string
                  resource_type:
                    anyOf:
                    - type: string
                  resource_id:
                    anyOf:
                    - type: string
                required:
                - _tag
                additionalProperties: false
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  _tag:
                    type: string
                    enum:
                    - '@superwall/api-schema/v2/errors/InternalError'
                  type:
                    anyOf:
                    - type: string
                      enum:
                      - api_error
                      - authentication_error
                      - invalid_request_error
                      - rate_limit_error
                      - permission_error
                  code:
                    anyOf:
                    - type: string
                      enum:
                      - resource_missing
                      - resource_already_exists
                      - resource_archived
                      - parameter_invalid
                      - parameter_missing
                      - parameter_unknown
                      - invalid_reference
                      - unsupported_operation
                      - idempotency_key_in_use
                      - rate_limit_exceeded
                      - invalid_api_key
                      - invalid_api_key_format
                      - missing_api_key
                      - authentication_failed
                      - invalid_session
                      - organization_required
                      - insufficient_permissions
                      - internal_error
                      - upstream_service_error
                      - side_effect_failed
                  message:
                    anyOf:
                    - type: string
                  cause:
                    anyOf:
                    - {}
                required:
                - _tag
                additionalProperties: false
      description: 'Returns the identifier and name for a paywall id, scoped to the application in the caller''s preview capability (sat_ or API-minted pvt_), sent as Authorization: Bearer . Returns 404 if the token is missing/invalid or the paywall does not belong to that application.'
      summary: Resolve Paywall by ID
  /v2/paywalls/preview-list:
    get:
      tags:
      - Paywall Resolver (Public)
      operationId: paywallresolvev2.listPreviewPaywalls
      parameters: []
      security: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        identifier:
                          type: string
                          description: URL-safe identifier (slug) for the paywall
                        name:
                          type: string
                          description: Display name of the paywall
                      required:
                      - id
                      - identifier
                      - name
                      additionalProperties: false
                  has_more:
                    type: boolean
                    description: True when the application has more paywalls than the returned cap
                  application_id:
                    type: string
                required:
                - object
                - data
                - has_more
                - application_id
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  _tag:
                    type: string
                    enum:
                    - HttpApiDecodeError
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        _tag:
                          type: string
                          enum:
                          - Type
                          - Missing
                          - Unexpected
                          - Forbidden
                          - Pointer
                          - Refinement
                          - Transformation
                          - Composite
                        path:
                          type: array
                          items:
                            anyOf:
                            - type: string
                            - type: number
                            - type: object
                              properties:
                                _tag:
                                  type: string
                                  enum:
                                  - symbol
                                key:
                                  type: string
                              required:
                              - _tag
                              - key
                              additionalProperties: false
                        message:
                          type: string
                      required:
                      - _tag
                      - path
                      - message
                      additionalProperties: false
                  message:
                    type: string
                required:
                - _tag
                - issues
                - message
                additionalProperties: false
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  _tag:
                    type: string
                    enum:
                    - '@superwall/api-schema/v2/errors/ResourceNotFound'
                  type:
                    anyOf:
                    - type: string
                      enum:
                      - api_error
                      - authentication_error
                      - invalid_request_error
                      - rate_limit_error
                      - permission_error
                  code:
                    anyOf:
                    - type: string
                      enum:
                      - resource_missing
                      - resource_already_exists
                      - resource_archived
                      - parameter_invalid
                      - parameter_missing
                      - parameter_unknown
                      - invalid_reference
                      - unsupported_operation
                      - idempotency_key_in_use
                      - rate_limit_exceeded
                      - invalid_api_key
                      - invalid_api_key_format
                      - missing_api_key
                      - authentication_failed
                      - invalid_session
                      - organization_required
                      - insufficient_permissions
                      - internal_error
                      - upstream_service_error
                      - side_effect_failed
                  message:
                    anyOf:
                    - type: string
                  param:
                    anyOf:
                    - type: string
                  doc_url:
                    anyOf:
                    - type: string
                  resource_type:
                    anyOf:
                    - type: string
                  resource_id:
                    anyOf:
                    - type: string
                required:
                - _tag
                additionalProperties: false
        '500':
          description: An unexpected error occurred on the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  _tag:
                    type: string
                    enum:
                    - '@superwall/api-schema/v2/errors/InternalError'
                  type:
                    anyOf:
                    - type: string
                      enum:
                      - api_error
                      - authentication_error
                      - invalid_request_error
                      - rate_limit_error
                      - permission_error
                  code:
                    anyOf:
                    - type: string
                      enum:
                      - resource_missing
                      - resource_already_exists
                      - resource_archived
                      - parameter_invalid
                      - parameter_missing
                      - parameter_unknown
                      - invalid_reference
                      - unsupported_operation
                      - idempotency_key_in_use
                      - rate_limit_exceeded
                      - invalid_api_key
                      - invalid_api_key_format
                      - missing_api_key
                      - authentication_failed
                      - invalid_session
                      - organization_required
                      - insufficient_permissions
                      - internal_error
                      - upstream_service_error
                      - side_effect_failed
                  message:
                    anyOf:
                    - type: string
                  cause:
                    anyOf:
                    - {}
                required:
                - _tag
                additionalProperties: false
      description: 'Returns id, identifier and name for non-archived paywalls allowed by the caller''s preview capability (sat_ or API-minted pvt_), sent as Authorization: Bearer . Paywall-scoped pvt_ tokens return one item; application-scoped pvt_ tokens enable the full picker. Returns 404 if the token is missing or invalid.'
      summary: List Paywalls for Preview
components:
  securitySchemes:
    bearer:
      type: http
      scheme: Bearer
    cookie:
      type: apiKey
      name: accounts_superwall_token
      in: cookie
    oauth:
      type: http
      scheme: Bearer