Aura Historia Notifications API

openapi: 3.2.0
info:
  title: Aura Historia API Reference Notifications API
  description: '## Overview


    The Aura Historia API powers the Aura Historia antiques platform and its partner-facing integrations. It exposes product discovery, listing source discovery, personalization, partner onboarding, and integration

    workflows on top of Aura Historia''s serverless AWS platform. This reference is designed for two audiences:

    - **Internal developers** building Aura Historia product-listings, operational tooling, and backoffice workflows

    - **External partners and integrators** synchronizing inventory, consuming platform data, or

    integrating with delegated access


    ## Core API domains


    - **ProductListings and listing-sources** — search, retrieve, and explore product-listings, related product-listings, product

    history, and listing source data

    - **Personalization** — manage watchlists, saved search filters, and user notifications

    - **Partner workflows** — submit partnership applications, maintain partnerships, ingest catalog data

    in batches, and receive WooCommerce webhooks

    - **Identity and access** — manage user accounts, Aura Historia access tokens, and OAuth 2.0

    clients and token flows

    - **Billing** — create Stripe checkout, billing-portal, and subscription-management sessions


    ## Authentication model


    The API uses more than one authentication scheme depending on the route:


    - **`BearerAuth`** — Cognito **access** JWT bearer tokens for authenticated user, admin, and

    partner-user workflows. Cognito ID tokens are not accepted as API credentials. - **`AccessTokenAuth`** — Aura Historia opaque bearer access tokens created via

    `/v1/me/access-tokens` or OAuth 2.0, primarily intended for partner automations and server-to-server

    ingestion scenarios. When a route lists multiple security schemes, any one of the listed schemes may be accepted. Some read endpoints can also be called without authentication, while a valid user token may enrich

    the response with personalized state such as watchlist, notification, or search-filter metadata. Aura Historia access

    tokens receive only the sections their read scopes permit; see `ProductListingUserStateData`. ## MCP interface


    The separate `https://mcp.aura-historia.com/v1` Streamable HTTP endpoint accepts opaque Aura access tokens only. Public calls may omit credentials; invalid supplied credentials receive HTTP 401, protected operations require their declared scopes, and insufficient grants receive HTTP 403 with the complete required scope set. Credential-free protected-resource metadata is served on the MCP host at `/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/v1`. See the MCP contract for protocol and discovery details. ## Data and response conventions


    - **PATCH:** an omitted request member remains unchanged. A documented nullable PATCH member

    accepts `null` to clear its value; `null` for any other member returns `400 BAD_BODY_VALUE`. Use `[]`, not `null`, to replace a non-null collection with an empty collection. Empty HTTP

    bodies are invalid, `{}` is a valid object-PATCH no-op, and the partner-product PATCH `[]`

    remains a valid empty batch. Responses may omit absent optional values. - Product detail, watchlist, and saved-search match reads accept optional **`language`** and

    **`currency`** parameters. Currency defaults to `EUR`. Detail pricing contains the seller''s source

    amounts, converted display amounts, and FX valuation metadata. Active product-listings use the latest persisted

    snapshot; sold product-listings use their immutable sale snapshot. Product history preserves immutable source values and accepts optional `currency` for historical FX display projections. History text is not localized. - Request-wide REST errors are returned as **`application/problem+json`** using a consistent RFC 9457-style structure

    with `status`, `title`, `error`, optional `source`, and optional `detail`.'
  version: 1.0.0
  contact:
    name: Aura-Historia Team
    url: https://aura-historia.com/
  license:
    name: License
    url: https://github.com/aura-historia/backend/blob/develop/LICENSE
servers:
- url: https://api.stage.aura-historia.com
  description: Development environment
- url: https://api.aura-historia.com
  description: Production environment
tags:
- name: Notifications
  description: In-app notification retrieval, bulk updates, single-notification updates, and notification cleanup workflows.
paths:
  /v1/me/notifications:
    get:
      summary: List user notifications
      description: 'Delegated Aura access tokens require `notifications:read`; missing scope returns `403 FORBIDDEN`. Retrieves the authenticated user’s canonical notifications in newest-first order.

        Watchlist price-change notifications preserve each event’s immutable source currency; no FX conversion

        is applied from the user’s preferences. Product image URLs are presented according to the authenticated

        user’s `showUnassessedOrSensitiveContent` preference.'
      operationId: listNotifications
      tags:
      - Notifications
      parameters:
      - name: language
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/LanguageData'
      - name: size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 21
      - name: searchAfter
        in: query
        required: false
        description: Opaque JSON `[created RFC3339 timestamp, Notification ID]` cursor returned by the prior page.
        schema:
          type: string
      security:
      - BearerAuth: []
      - AccessTokenAuth: []
      responses:
        '200':
          description: Notifications retrieved successfully.
          headers:
            Cache-Control:
              schema:
                type: string
              example: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationCollectionData'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden - required delegated scope missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Invalid or missing bearer credential
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Notifications are temporarily unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
    patch:
      summary: Update selected notification seen states
      description: Delegated Aura access tokens require `notifications:write`; missing scope returns `403 FORBIDDEN`. Updates the seen state for the explicit canonical notification IDs in the request body.
      operationId: updateNotificationsSeen
      tags:
      - Notifications
      security:
      - BearerAuth: []
      - AccessTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationsSeenData'
      responses:
        '204':
          description: Selected notifications updated.
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden - required delegated scope missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Invalid or missing bearer credential
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Notifications are temporarily unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
    delete:
      summary: Delete all notifications
      description: Delegated Aura access tokens require `notifications:write`; missing scope returns `403 FORBIDDEN`.
      operationId: deleteNotifications
      tags:
      - Notifications
      security:
      - BearerAuth: []
      - AccessTokenAuth: []
      responses:
        '204':
          description: Notifications deleted.
        '403':
          description: Forbidden - required delegated scope missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Invalid or missing bearer credential
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Notifications are temporarily unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/me/notifications/all:
    patch:
      summary: Update all notification seen states
      description: Delegated Aura access tokens require `notifications:write`; missing scope returns `403 FORBIDDEN`.
      operationId: updateAllNotificationsSeen
      tags:
      - Notifications
      security:
      - BearerAuth: []
      - AccessTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationSeenData'
      responses:
        '204':
          description: Notifications updated.
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden - required delegated scope missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Invalid or missing bearer credential
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Notifications are temporarily unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/me/notifications/{notificationId}:
    patch:
      summary: Update one notification seen state
      description: Delegated Aura access tokens require `notifications:write`; missing scope returns `403 FORBIDDEN`.
      operationId: updateNotificationSeen
      tags:
      - Notifications
      security:
      - BearerAuth: []
      - AccessTokenAuth: []
      parameters:
      - name: notificationId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNotificationSeenData'
      responses:
        '204':
          description: Notification updated.
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden - required delegated scope missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Invalid or missing bearer credential
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Notifications are temporarily unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Notification not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
    delete:
      summary: Delete one notification
      description: Delegated Aura access tokens require `notifications:write`; missing scope returns `403 FORBIDDEN`.
      operationId: deleteNotification
      tags:
      - Notifications
      security:
      - BearerAuth: []
      - AccessTokenAuth: []
      parameters:
      - name: notificationId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Notification deleted.
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Forbidden - required delegated scope missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Invalid or missing bearer credential
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Notifications are temporarily unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: Notification not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    LocalizedTextData:
      type: object
      description: Text content with language information
      required:
      - text
      - language
      properties:
        text:
          type: string
          description: The text content
        language:
          $ref: '#/components/schemas/LanguageData'
    LanguageData:
      type: string
      enum:
      - de
      - en
      - fr
      - es
      - it
      - zh
      - pt
      - pl
      - tr
      - nl
      - cs
      - ja
      - ru
      - ar
      description: 'Supported language codes (ISO 639-1 canonical values):

        - de: German (includes de-DE, de-AT, de-CH, de-LU, de-LI)

        - en: English (includes en-US, en-GB, en-AU, en-CA, en-NZ, and backend-specific accepted alias en_IE)

        - fr: French (includes fr-FR, fr-CA, fr-BE, fr-CH, fr-LU)

        - es: Spanish (includes es-ES, es-MX, es-AR, es-CO, es-CL, es-PE, es-VE)

        - it: Italian (includes it-IT, it-CH)

        - zh: Chinese (Simplified) (includes zh-CN, zh-Hans)

        - pt: Portuguese (includes pt-PT, pt-BR)

        - pl: Polish (includes pl-PL)

        - tr: Turkish (includes tr-TR)

        - nl: Dutch (includes nl-NL, nl-BE)

        - cs: Czech (includes cs-CZ)

        - ja: Japanese (includes ja-JP)

        - ru: Russian (includes ru-RU)

        - ar: Arabic (includes ar-SA, ar-EG, ar-AE)


        `de`, `en`, `fr`, `es`, and `it` are fully supported localization/translation-target languages.

        `zh`, `pt`, `pl`, `tr`, `nl`, `cs`, `ja`, `ru`, and `ar` are ingestion-only languages:

        they can appear in stored/native content and are accepted anywhere `LanguageData` is used,

        but backend-generated translations and fallback localized strings are not produced in these languages.

        '
      default: en
      example: de
    WatchlistNotificationPriceChangeData:
      type: object
      required:
      - type
      - oldPrice
      - newPrice
      properties:
        type:
          type: string
          enum:
          - PRICE_CHANGE
        oldPrice:
          allOf:
          - $ref: '#/components/schemas/ProductListingPriceData'
          description: Previous asking-price assertion. Null when unavailable.
        newPrice:
          allOf:
          - $ref: '#/components/schemas/ProductListingPriceData'
          description: New asking-price assertion. Null when unavailable.
    WatchlistNotificationChangeData:
      oneOf:
      - $ref: '#/components/schemas/WatchlistNotificationPriceChangeData'
      - $ref: '#/components/schemas/WatchlistNotificationAvailabilityChangeData'
    ApiErrorSource:
      type: object
      description: Information about the source of the error
      required:
      - field
      - type
      properties:
        field:
          type: string
          description: Name of the field that caused the error
          example: listingSourceId
        type:
          type: string
          enum:
          - QUERY
          - PATH
          - HEADER
          - BODY
          description: Type of parameter that caused the error
          example: PATH
    WatchlistNotificationAvailabilityChangeData:
      type: object
      required:
      - type
      - oldAvailability
      - newAvailability
      properties:
        type:
          type: string
          enum:
          - AVAILABILITY_CHANGE
        oldAvailability:
          allOf:
          - $ref: '#/components/schemas/ListingAvailabilityData'
        newAvailability:
          allOf:
          - $ref: '#/components/schemas/ListingAvailabilityData'
    UpdateNotificationSeenData:
      type: object
      required:
      - seen
      properties:
        seen:
          type: boolean
    ApiError:
      type: object
      description: Standard error response format (RFC 9457)
      required:
      - status
      - title
      - error
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        title:
          type: string
          description: HTTP status code in human-readable form
          example: Bad Request
        error:
          type: string
          description: Error code identifier
          example: BAD_PARAMETER
        source:
          $ref: '#/components/schemas/ApiErrorSource'
        detail:
          type: string
          description: Human-readable error message
          example: 'Expected any of: ''true'' or ''false''. Got: ''invalid'''
    ListingAvailabilityData:
      type: string
      enum:
      - AVAILABLE
      - IN_STOCK
      - LIMITED_AVAILABILITY
      - BACK_ORDER
      - MADE_TO_ORDER
      - PRE_ORDER
      - PRE_SALE
      - UNAVAILABLE
      - RESERVED
      - OUT_OF_STOCK
      - SOLD_OUT
      description: Current reliable source assertion of listing purchase availability. Omitted or `null` means Aura has no reliable current assertion.
      example: IN_STOCK
    NotificationCollectionData:
      type: object
      required:
      - items
      - size
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NotificationData'
        size:
          type: integer
          minimum: 0
          maximum: 100
          description: Number of items returned in the current page.
        searchAfter:
          type:
          - array
          - 'null'
          minItems: 2
          maxItems: 2
          items:
            type: string
          description: Opaque `[created RFC3339 timestamp, Notification ID]` cursor for the next page; omitted when no further page exists.
    WatchlistNotificationPayloadData:
      type: object
      required:
      - productListingId
      - listingSourceId
      - sourceListingId
      - listingSourceSlugId
      - productListingTitleSlugId
      - listingSourceName
      - title
      - image
      - url
      - viewUrl
      - change
      properties:
        productListingId:
          type: string
        listingSourceId:
          type: string
        sourceListingId:
          type: string
        listingSourceSlugId:
          type: string
        productListingTitleSlugId:
          type: string
        listingSourceName:
          type: string
        title:
          allOf:
          - $ref: '#/components/schemas/LocalizedTextData'
        image:
          allOf:
          - $ref: '#/components/schemas/ProductListingImageData'
        url:
          type: string
          format: uri
        viewUrl:
          type: string
          format: uri
        change:
          $ref: '#/components/schemas/WatchlistNotificationChangeData'
    UpdateNotificationsSeenData:
      type: object
      required:
      - notificationIds
      - seen
      properties:
        notificationIds:
          type: array
          minItems: 1
          items:
            type: string
        seen:
          type: boolean
    ProductListingPriceData:
      oneOf:
      - type: object
        required:
        - type
        - currency
        - amount
        additionalProperties: false
        properties:
          type:
            type: string
            enum:
            - MONETARY
          currency:
            $ref: '#/components/schemas/CurrencyData'
          amount:
            type: integer
            minimum: 0
      - type: object
        required:
        - type
        additionalProperties: false
        properties:
          type:
            type: string
            enum:
            - ON_REQUEST
    ProductListingImageData:
      type: object
      description: Product image after viewer-specific presentation.
      required:
      - url
      properties:
        url:
          type:
          - string
          - 'null'
          format: uri
          description: URL to the product image, or `null` when it is not shown to this viewer.
          example: https://my-listing-source.com/images/product-1.jpg
    PartnershipApplicationNotificationPayloadData:
      type: object
      required:
      - partnershipApplicationId
      - decision
      - listingSourceName
      - image
      properties:
        partnershipApplicationId:
          type: string
        decision:
          type: string
          enum:
          - APPROVED
          - REJECTED
        listingSourceName:
          type: string
        image:
          type:
          - string
          - 'null'
          format: uri
    CurrencyData:
      type: string
      enum:
      - EUR
      - GBP
      - USD
      - AUD
      - CAD
      - NZD
      - CNY
      - BRL
      - PLN
      - TRY
      - JPY
      - CZK
      - RUB
      - AED
      - SAR
      - HKD
      - SGD
      - CHF
      - ZAR
      - SEK
      - DKK
      - NOK
      - KRW
      - INR
      - TWD
      - HUF
      - RON
      - MXN
      - THB
      - ARS
      description: 'Supported currencies (ISO 4217 codes):

        - EUR: Euro

        - GBP: British Pound

        - USD: US Dollar

        - AUD: Australian Dollar

        - CAD: Canadian Dollar

        - NZD: New Zealand Dollar

        - CNY: Chinese Yuan

        - BRL: Brazilian Real

        - PLN: Polish Złoty

        - TRY: Turkish Lira

        - JPY: Japanese Yen

        - CZK: Czech Koruna

        - RUB: Russian Ruble

        - AED: UAE Dirham

        - SAR: Saudi Riyal

        - HKD: Hong Kong Dollar

        - SGD: Singapore Dollar

        - CHF: Swiss Franc

        - ZAR: South African Rand

        - SEK: Swedish Krona

        - DKK: Danish Krone

        - NOK: Norwegian Krone

        - KRW: South Korean Won

        - INR: Indian Rupee

        - TWD: New Taiwan Dollar

        - HUF: Hungarian Forint

        - RON: Romanian Leu

        - MXN: Mexican Peso

        - THB: Thai Baht

        - ARS: Argentine Peso (2 minor-unit decimal places)

        '
      default: EUR
      example: EUR
    NotificationPayloadData:
      description: Reason-specific immutable snapshot. Its shape is selected by the parent `NotificationData.kind`.
      oneOf:
      - $ref: '#/components/schemas/WatchlistNotificationPayloadData'
      - $ref: '#/components/schemas/SearchFilterNotificationPayloadData'
      - $ref: '#/components/schemas/PartnershipApplicationNotificationPayloadData'
    NotificationData:
      type: object
      required:
      - notificationId
      - kind
      - payload
      - seen
      - created
      - updated
      properties:
        notificationId:
          type: string
        kind:
          type: string
          enum:
          - WATCHLIST_PRICE_CHANGED
          - WATCHLIST_AVAILABILITY_CHANGED
          - SEARCH_FILTER_MATCH
          - PARTNERSHIP_APPLICATION_APPROVED
          - PARTNERSHIP_APPLICATION_REJECTED
        payload:
          $ref: '#/components/schemas/NotificationPayloadData'
        seen:
          type: boolean
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
          description: When the notification state (such as `seen`) last changed; repeating an identical state leaves it unchanged.
    SearchFilterNotificationPayloadData:
      type: object
      required:
      - productListingId
      - userSearchFilterId
      - userSearchFilterName
      - listingSourceId
      - sourceListingId
      - listingSourceSlugId
      - productListingTitleSlugId
      - listingSourceName
      - title
      - image
      - url
      - viewUrl
      properties:
        productListingId:
          type: string
        userSearchFilterId:
          type: string
        userSearchFilterName:
          type: string
        listingSourceId:
          type: string
        sourceListingId:
          type: string
        listingSourceSlugId:
          type: string
        productListingTitleSlugId:
          type: string
        listingSourceName:
          type: string
        title:
          allOf:
          - $ref: '#/components/schemas/LocalizedTextData'
        image:
          allOf:
          - $ref: '#/components/schemas/ProductListingImageData'
        url:
          type: string
          format: uri
        viewUrl:
          type: string
          format: uri
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Cognito access JWT bearer token. Signature, issuer, client, token use and expiry

        are validated locally. Signed integer `auth_time` and `iat` claims are required;

        sessions authenticated at or before the persisted local revocation cutoff are rejected.

        This check shares the existing identity lookup and makes no live Cognito status request.

        Revocation requested only in Cognito is not observed immediately; already-issued JWTs

        can remain accepted until expiry. Use the administrator session-revocation endpoint

        for immediate local enforcement. Database authentication failures return

        `503 AUTH_TEMPORARILY_UNAVAILABLE`.

        This scheme is used for authenticated user routes and for partner routes that accept Cognito user tokens.

        '
    AccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: 'Aura Historia bearer access token created through `/v1/me/access-tokens`.

        Tokens are sent as standard bearer authorization headers.

        Selected partner routes accept this scheme instead of the removed partner API-key flow.

        '
x-tagGroups:
- name: Operations
  tags:
  - Operations
- name: Discovery
  tags:
  - ProductListings
  - ListingSources
  - Auctions
- name: User Experience
  tags:
  - Search Filters
  - Watchlist
  - Notifications
  - User Account
  - Billing
  - Newsletter
- name: Partner & Platform Integrations
  tags:
  - Partnerships
  - PartnershipApplications
  - OAuth