NimbusNexus V1:account:subscriptions API

openapi: 3.2.0
info:
  title: NimbusNexus API — External V1:account:subscriptions API
  description: 'External (public) API intended for client-facing integrations and the web portal.


    Authentication:

    - This API uses JWT Bearer authentication.

    - In Swagger UI, click ''Authorize'' and sign in via the configured token endpoint.

    - Swagger will automatically attach the header: Authorization: Bearer .'
  version: test
servers:
- url: /
  description: Current host
- url: https://fastapi.dev.nimbusnexus.net
  description: Development
security:
- SwaggerLogin: []
- ApiKeyAuth: []
tags:
- name: v1:account:subscriptions
paths:
  /api/v1/account/subscriptions:
    get:
      tags:
      - v1:account:subscriptions
      summary: List My Subscriptions
      description: 'Returns the current user''s subscription preferences across every

        channel they have a row for, including ones taken before they had

        an account (linked by email at registration time).'
      operationId: list_my_subscriptions_api_v1_account_subscriptions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListOut'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Unauthorized | Invalid token | Expired token | Authentication required
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                code: 429
                message: Too many requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Internal Server Error
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
    post:
      tags:
      - v1:account:subscriptions
      summary: Subscribe
      description: 'Anonymous subscribe. Sends a double-opt-in email if any requested

        channel is new or previously unsubscribed; otherwise returns success

        silently (idempotent — does not leak whether email is already on the list).

        Originating IP is captured for fraud forensics; auto-purged after 365

        days by the retention job.'
      operationId: subscribe_api_v1_account_subscriptions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscribeIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeSuccessOut'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Bad Request
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseValidationErrorOut'
              example:
                success: false
                errors:
                  field:
                  - Invalid value
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                code: 429
                message: Too many requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Internal Server Error
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
    patch:
      tags:
      - v1:account:subscriptions
      summary: Edit My Subscriptions
      description: 'Bulk add/remove channels for the authenticated user. Skips double

        opt-in for added channels — the email is already verified as part

        of the user''s account.'
      operationId: edit_my_subscriptions_api_v1_account_subscriptions_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListOut'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Unauthorized | Invalid token | Expired token | Authentication required
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseValidationErrorOut'
              example:
                success: false
                errors:
                  field:
                  - Invalid value
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                code: 429
                message: Too many requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Internal Server Error
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
  /api/v1/account/subscriptions/confirm:
    post:
      tags:
      - v1:account:subscriptions
      summary: Confirm
      description: 'Confirms a subscription via the token from the validation email.

        Flips matching pending rows to confirmed and sends a welcome email.'
      operationId: confirm_api_v1_account_subscriptions_confirm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeSuccessOut'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Bad Request
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseValidationErrorOut'
              example:
                success: false
                errors:
                  field:
                  - Invalid value
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                code: 429
                message: Too many requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Internal Server Error
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
  /api/v1/account/subscriptions/unsubscribe:
    post:
      tags:
      - v1:account:subscriptions
      summary: Unsubscribe
      description: 'Token-scoped unsubscribe. Default scope is the single channel the

        token was issued for (so an unsubscribe link in an articles email

        cannot affect billing or vm_events). Pass `all_channels=true` to

        unsubscribe every channel for the resolved email.'
      operationId: unsubscribe_api_v1_account_subscriptions_unsubscribe_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnsubscribeIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscribeSuccessOut'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Bad Request
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Not Found
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseValidationErrorOut'
              example:
                success: false
                errors:
                  field:
                  - Invalid value
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                code: 429
                message: Too many requests
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
              example:
                success: false
                message: Internal Server Error
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
  /api/v1/account/subscriptions/preferences:
    get:
      tags:
      - v1:account:subscriptions
      summary: Get Preferences
      description: 'Read every subscription row for the email this token resolves to.


        Public, no JWT — the token (per-row ``unsubscribe_token``) acts as

        the proof of identity. Used by the email-preferences page in

        Frontend-index, which the recipient lands on via a tokenized link

        from any marketing email''s footer.


        The UI overlays this against the canonical channel list to render

        every channel as on/off — channels the user has never subscribed

        to simply won''t appear in the response and render as off.'
      operationId: get_preferences_api_v1_account_subscriptions_preferences_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListOut'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                success: false
                message: Bad Request
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                success: false
                message: Not Found
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '422':
          description: Validation error
          content:
            application/json:
              example:
                success: false
                errors:
                  field:
                  - Invalid value
              schema:
                $ref: '#/components/schemas/ResponseValidationErrorOut'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              example:
                code: 429
                message: Too many requests
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                success: false
                message: Internal Server Error
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
    patch:
      tags:
      - v1:account:subscriptions
      summary: Update Preferences
      description: 'Bulk add/remove channels for the recipient identified by ``token``.


        Token-scoped (no JWT). Only public channels (articles,

        product_updates) are editable here — attempts to add or remove

        non-public channels (vm_events, billing) are rejected with 403.

        Those require the authenticated PATCH endpoint.


        Returns the recipient''s full current state across every channel,

        same shape as the authenticated ``PATCH /account/subscriptions``.'
      operationId: update_preferences_api_v1_account_subscriptions_preferences_patch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreferencesUpdateIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListOut'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                success: false
                message: Bad Request
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                success: false
                message: Forbidden
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '404':
          description: Not Found
          content:
            application/json:
              example:
                success: false
                message: Not Found
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '422':
          description: Validation error
          content:
            application/json:
              example:
                success: false
                errors:
                  field:
                  - Invalid value
              schema:
                $ref: '#/components/schemas/ResponseValidationErrorOut'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying the request
              schema:
                type: string
              example: '30'
          content:
            application/json:
              example:
                code: 429
                message: Too many requests
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
        '500':
          description: Internal Server Error
          content:
            application/json:
              example:
                success: false
                message: Internal Server Error
              schema:
                $ref: '#/components/schemas/ResponseBaseErrorOut'
      security:
      - SwaggerLogin: []
      - ApiKeyAuth: []
components:
  schemas:
    SubscriptionListOut:
      properties:
        success:
          type: boolean
          title: Success
          default: true
        data:
          items:
            $ref: '#/components/schemas/SubscriptionPreferenceOut'
          type: array
          title: Data
      type: object
      required:
      - data
      title: SubscriptionListOut
    ConfirmIn:
      properties:
        token:
          type: string
          minLength: 1
          title: Token
      type: object
      required:
      - token
      title: ConfirmIn
    SubscriptionPreferenceOut:
      properties:
        id:
          type: string
          title: Id
        email:
          type: string
          title: Email
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        channel:
          $ref: '#/components/schemas/SubscriptionChannelEnum'
        status:
          $ref: '#/components/schemas/SubscriptionStatusEnum'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        confirmed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Confirmed At
        unsubscribed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Unsubscribed At
      type: object
      required:
      - id
      - email
      - channel
      - status
      - created_at
      - updated_at
      title: SubscriptionPreferenceOut
    SubscriptionChannelEnum:
      type: string
      enum:
      - articles
      - product_updates
      - vm_events
      - billing
      title: SubscriptionChannelEnum
      description: 'Channels a recipient can subscribe to. Public channels can be set

        from the anonymous /subscriptions endpoint; non-public ones require an

        authenticated session and are managed from the portal preferences page.

        Public/non-public is enforced in the API layer, not the model.'
    SubscriptionStatusEnum:
      type: string
      enum:
      - pending
      - confirmed
      - unsubscribed
      title: SubscriptionStatusEnum
    SubscriptionUpdate:
      properties:
        add:
          items:
            $ref: '#/components/schemas/SubscriptionChannelEnum'
          type: array
          title: Add
        remove:
          items:
            $ref: '#/components/schemas/SubscriptionChannelEnum'
          type: array
          title: Remove
      type: object
      title: SubscriptionUpdate
      description: 'Authenticated bulk edit. Either or both lists may be empty — channels

        in `add` are upserted to confirmed (skipping double-opt-in since the

        user is already authenticated); channels in `remove` are unsubscribed.'
    PreferencesUpdateIn:
      properties:
        token:
          type: string
          minLength: 1
          title: Token
        add:
          items:
            $ref: '#/components/schemas/SubscriptionChannelEnum'
          type: array
          title: Add
        remove:
          items:
            $ref: '#/components/schemas/SubscriptionChannelEnum'
          type: array
          title: Remove
      type: object
      required:
      - token
      title: PreferencesUpdateIn
      description: 'Token-scoped bulk edit body for ``PATCH /subscriptions/preferences``.


        Same `add` / `remove` semantics as `SubscriptionUpdate`, plus the per-row

        `unsubscribe_token` from the marketing email that brought the recipient

        to the preferences page — no JWT required. The router enforces that only

        public channels (articles, product_updates) appear in either list.'
    UnsubscribeIn:
      properties:
        token:
          type: string
          minLength: 1
          title: Token
        all_channels:
          type: boolean
          title: All Channels
          default: false
      type: object
      required:
      - token
      title: UnsubscribeIn
      description: 'Token-scoped unsubscribe. `channel` defaults to the channel the token

        was issued for; passing ''all'' unsubscribes every channel for the email

        the token resolves to.'
    SubscribeIn:
      properties:
        email:
          type: string
          format: email
          title: Email
        channels:
          items:
            $ref: '#/components/schemas/SubscriptionChannelEnum'
          type: array
          minItems: 1
          title: Channels
      type: object
      required:
      - email
      - channels
      title: SubscribeIn
      description: 'Anonymous subscribe request body. The API layer enforces that every

        channel listed here is in the public allowlist — non-public channels

        (vm_events, billing) require authenticated PATCH instead.'
    ResponseBaseErrorOut:
      properties:
        success:
          type: boolean
          title: Success
          default: false
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: ResponseBaseErrorOut
    ResponseValidationErrorOut:
      properties:
        success:
          type: boolean
          title: Success
          default: false
        errors:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Errors
      type: object
      required:
      - errors
      title: ResponseValidationErrorOut
    SubscribeSuccessOut:
      properties:
        success:
          type: boolean
          title: Success
          default: true
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
      type: object
      title: SubscribeSuccessOut
      description: 'Returned for anonymous subscribe / confirm / unsubscribe. Intentionally

        minimal — leaks no information about whether the email was already on

        the list (idempotent + privacy-preserving).'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    SwaggerLogin:
      type: oauth2
      flows:
        password:
          tokenUrl: /api/v1/account/login_swagger
          scopes: {}
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API Key format -  base64('<id>:<secret>')