Aura Historia Parties API

openapi: 3.2.0
info:
  title: Aura Historia API Reference Parties 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: Parties
paths:
  /v1/party-locations:
    get:
      summary: Discover public Party locations
      operationId: discoverPartyLocations
      tags:
      - Parties
      security: []
      description: Location-oriented discovery of eligible active Party sites. Multiple matching sites of one Party intentionally appear as separate locations. Country/subdivision predicates need no coordinates. Radius or distance ordering requires an explicit numeric origin. Strict proximity requires PREMISES precision; approximate mode retains coarse labels. Ordered by distance when requested, then native location UUID ascending; otherwise UUID ascending. Reads current PostgreSQL locations independently of listing projection catch-up. All responses are private, no-store. Management evidence, addresses and revisions stay private.
      parameters:
      - name: geography
        in: query
        required: true
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/GeographicSearchData'
      - name: size
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 21
      - name: searchAfter
        in: query
        style: deepObject
        explode: true
        schema:
          $ref: '#/components/schemas/PartyLocationDiscoveryCursorData'
      responses:
        '200':
          description: Matching public locations.
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                - size
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PublicPartyLocationData'
                  size:
                    type: integer
                  searchAfter:
                    $ref: '#/components/schemas/PartyLocationDiscoveryCursorData'
        '400':
          description: Invalid geographic predicates, origin or continuation (BAD_QUERY_PARAMETER_VALUE).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Location read unavailable (PARTY_TEMPORARILY_UNAVAILABLE).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    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'''
    GeographicRadiusData:
      type: object
      additionalProperties: false
      required:
      - amount
      - unit
      description: Finite positive radius in the supplied unit, equivalent to at most 20000 kilometres. The supplied amount and unit are preserved in private saved-filter snapshots.
      properties:
        amount:
          type: number
          example: 25
          exclusiveMinimum: 0
        unit:
          type: string
          enum:
          - KILOMETERS
          - MILES
          - METERS
          - YARDS
          - FEET
          - INCHES
          - CENTIMETERS
          - MILLIMETERS
          - NAUTICAL_MILES
          example: KILOMETERS
      example:
        amount: 25
        unit: KILOMETERS
    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
    PartyLocationDiscoveryCursorData:
      type: object
      additionalProperties: false
      required:
      - locationId
      description: Repeat with the same query. distanceKm is required exactly when ordering by distance; it is an unrounded continuation value.
      properties:
        locationId:
          type: string
        distanceKm:
          type: number
          minimum: 0
    GeographicSearchData:
      type: object
      additionalProperties: false
      description: At least one country, subdivision, radius or distance order is required. Sets are OR; distinct geographic predicates are AND. Subdivisions must belong to a supplied country when countries is nonempty. Absence excludes a result. Radius and ordering require an explicit numeric origin; an origin or approximate mode without proximity is invalid. Strict proximity admits PREMISES only; approximate also admits STREET, LOCALITY and REPRESENTATIVE. Distance ordering is incompatible with the existing sort. Saved filters retain a private immutable snapshot until replaced.
      properties:
        countries:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            pattern: ^[A-Z]{2}$
          example:
          - DE
        subdivisions:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
          example:
          - DE-BY
        origin:
          $ref: '#/components/schemas/GeographicOriginData'
        radius:
          $ref: '#/components/schemas/GeographicRadiusData'
        mode:
          type: string
          enum:
          - STRICT
          - APPROXIMATE
          default: STRICT
        distanceOrder:
          type: string
          enum:
          - ASC
          - DESC
    GeographicOriginData:
      type: object
      additionalProperties: false
      required:
      - latitude
      - longitude
      description: Explicit finite numeric WGS 84 coordinates in degrees; no text, address or preference resolution.
      properties:
        latitude:
          type: number
          minimum: -90
          maximum: 90
        longitude:
          type: number
          minimum: -180
          maximum: 180
    PublicPartyLocationData:
      type: object
      required:
      - partyId
      - partyName
      - locationId
      - label
      - basis
      properties:
        partyId:
          type: string
        partyName:
          type: string
        locationId:
          type: string
        label:
          type: string
        basis:
          type: string
          enum:
          - CALLER_ASSERTED
          - ACCEPTED_DERIVED
          - MIXED_ASSERTED_AND_DERIVED
        country:
          type: string
        subdivision:
          type: string
        point:
          $ref: '#/components/schemas/GeographicOriginData'
        precision:
          type: string
          enum:
          - PREMISES
          - STREET
          - LOCALITY
          - REPRESENTATIVE
        distanceKm:
          type: number
          minimum: 0
          description: Rounded display distance following evidence precision.
  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