openapi: 3.0.3
info:
  title: FrontBooker Distribution API
  version: "1.0.0"
  description: |
    Read-only External Property Distribution Platform API.

    Authorized agents and affiliates can distribute FrontBooker's publicly eligible
    accommodation inventory through their own websites and applications via this
    isolated Distribution API Gateway.

    The gateway is completely isolated from FrontBooker's operational database and
    exposes no write, booking, payment, or financial operations.

    Authentication: API keys prefixed with `fb_live_` passed as `Bearer` tokens.
    One active API key per account. Permissions are enforced server-side on every request.
  contact:
    name: FrontBooker Developer Platform
    url: https://developers.frontbooker.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://distribution-api.frontbooker.com/v1
    description: Production
  - url: http://localhost:8787/v1
    description: Local development

tags:
  - name: search
    description: Property and destination search
  - name: discovery
    description: Discovery feeds, featured properties, and collections
  - name: properties
    description: Property details and media
  - name: booking_information
    description: Availability and pricing lookup (read-only)
  - name: integrations
    description: Website integration management (dashboard endpoints)
  - name: credentials
    description: API credential management (dashboard endpoints)
  - name: analytics
    description: Integration analytics
  - name: activity
    description: Activity and audit logs
  - name: admin
    description: Administrator oversight (session-authenticated)

paths:
  # ── Health ────────────────────────────────────────────────────────────────
  /health:
    get:
      summary: Health check
      tags: [search]
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  service:
                    type: string
                    example: frontbooker-distribution
                  version:
                    type: string
                    example: v1
                  timestamp:
                    type: string
                    format: date-time

  # ── Search ────────────────────────────────────────────────────────────────
  /search:
    get:
      summary: Universal property search
      tags: [search]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QueryCursor'
        - $ref: '#/components/parameters/QueryDestination'
        - $ref: '#/components/parameters/QueryCheckIn'
        - $ref: '#/components/parameters/QueryCheckOut'
        - $ref: '#/components/parameters/QueryGuests'
        - $ref: '#/components/parameters/QueryMinPrice'
        - $ref: '#/components/parameters/QueryMaxPrice'
        - $ref: '#/components/parameters/QueryPropertyType'
        - $ref: '#/components/parameters/QueryMinRating'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'

  /search/destinations:
    get:
      summary: Destination search
      tags: [search]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryDestination'
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          description: Destination suggestions
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        country:
                          type: string
                        property_count:
                          type: integer
                  meta:
                    $ref: '#/components/schemas/FreshnessMeta'

  /search/properties:
    get:
      summary: Filtered property search
      tags: [search]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryDestination'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QueryCursor'
        - $ref: '#/components/parameters/QueryCheckIn'
        - $ref: '#/components/parameters/QueryCheckOut'
        - $ref: '#/components/parameters/QueryGuests'
        - $ref: '#/components/parameters/QueryMinPrice'
        - $ref: '#/components/parameters/QueryMaxPrice'
        - $ref: '#/components/parameters/QueryPropertyType'
        - $ref: '#/components/parameters/QueryMinRating'
      responses:
        '200':
          description: Filtered search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'

  # ── Discovery ─────────────────────────────────────────────────────────────
  /discovery/feed:
    get:
      summary: Discovery feed
      tags: [discovery]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QueryCursor'
      responses:
        '200':
          $ref: '#/components/responses/DiscoveryFeed'

  /discovery/featured:
    get:
      summary: Featured properties
      tags: [discovery]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          $ref: '#/components/responses/DiscoveryFeed'

  /discovery/collections:
    get:
      summary: Curated collections
      tags: [discovery]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryLimit'
      responses:
        '200':
          $ref: '#/components/responses/DiscoveryFeed'

  # ── Properties ────────────────────────────────────────────────────────────
  /properties/{property_id}:
    get:
      summary: Property details
      tags: [properties]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PathPropertyId'
      responses:
        '200':
          description: Property detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyResponse'
        '404':
          description: Property not found

  /properties/{property_id}/media:
    get:
      summary: Property media (CDN URLs)
      tags: [properties]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/PathPropertyId'
      responses:
        '200':
          description: Property media
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          format: uri
                        type:
                          type: string
                        is_primary:
                          type: boolean
                  meta:
                    $ref: '#/components/schemas/FreshnessMeta'

  # ── Booking Information ───────────────────────────────────────────────────
  /availability:
    get:
      summary: Availability lookup
      tags: [booking_information]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryPropertyIds'
        - $ref: '#/components/parameters/QueryCheckIn'
        - $ref: '#/components/parameters/QueryCheckOut'
        - $ref: '#/components/parameters/QueryGuests'
      responses:
        '200':
          description: Availability results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AvailabilityResult'
                  meta:
                    $ref: '#/components/schemas/FreshnessMeta'

  /pricing:
    get:
      summary: Pricing lookup
      tags: [booking_information]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryPropertyIds'
        - $ref: '#/components/parameters/QueryCheckIn'
        - $ref: '#/components/parameters/QueryCheckOut'
        - $ref: '#/components/parameters/QueryGuests'
      responses:
        '200':
          description: Pricing results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PricingResult'
                  meta:
                    $ref: '#/components/schemas/FreshnessMeta'

  # ── Integrations (dashboard) ──────────────────────────────────────────────
  /api/distribution/integrations:
    get:
      summary: List integrations
      tags: [integrations]
      security:
        - SessionAuth: []
      responses:
        '200':
          description: Integrations list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Integration'
    post:
      summary: Register an integration
      tags: [integrations]
      security:
        - SessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '201':
          description: Integration created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Integration'

    patch:
      summary: Update an integration
      tags: [integrations]
      security:
        - SessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIntegrationRequest'
      responses:
        '200':
          description: Integration updated

    post:
      summary: Suspend an integration
      tags: [integrations]
      security:
        - SessionAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Integration suspended

  # ── Credentials (dashboard) ───────────────────────────────────────────────
  /api/distribution/credentials:
    get:
      summary: List credentials
      tags: [credentials]
      security:
        - SessionAuth: []
      responses:
        '200':
          description: Credentials list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiCredential'
    post:
      summary: Create a credential
      tags: [credentials]
      security:
        - SessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialRequest'
      responses:
        '201':
          description: Credential created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ApiCredential'
                  secret:
                    type: string
                    description: Plaintext secret shown once

    put:
      summary: Replace (rotate) a credential
      tags: [credentials]
      security:
        - SessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplaceCredentialRequest'
      responses:
        '200':
          description: Credential replaced

    delete:
      summary: Revoke a credential
      tags: [credentials]
      security:
        - SessionAuth: []
      responses:
        '200':
          description: Credential revoked

    patch:
      summary: Update permissions
      tags: [credentials]
      security:
        - SessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePermissionsRequest'
      responses:
        '200':
          description: Permissions updated

  # ── Analytics ─────────────────────────────────────────────────────────────
  /api/distribution/analytics/overview:
    get:
      summary: Analytics overview
      tags: [analytics]
      security:
        - SessionAuth: []
      responses:
        '200':
          description: Overview metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AnalyticsOverview'

  /api/distribution/analytics/traffic:
    get:
      summary: Traffic analytics
      tags: [analytics]
      security:
        - SessionAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryStartDate'
        - $ref: '#/components/parameters/QueryEndDate'
      responses:
        '200':
          description: Traffic data

  /api/distribution/analytics/conversions:
    get:
      summary: Conversion analytics
      tags: [analytics]
      security:
        - SessionAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryStartDate'
        - $ref: '#/components/parameters/QueryEndDate'
      responses:
        '200':
          description: Conversion data

  # ── Activity logs ─────────────────────────────────────────────────────────
  /api/distribution/activity/logs:
    get:
      summary: Activity logs
      tags: [activity]
      security:
        - SessionAuth: []
      parameters:
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QueryCursor'
      responses:
        '200':
          description: Activity log entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityLogEntry'
                  pagination:
                    $ref: '#/components/schemas/PaginationMeta'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Bearer token with your API key (e.g. Bearer fb_live_...)
    SessionAuth:
      type: apiKey
      in: header
      name: Cookie
      description: Session cookie for dashboard endpoints

  parameters:
    QueryLimit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      description: Maximum number of results to return
    QueryCursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Opaque cursor for pagination
    QueryDestination:
      name: destination
      in: query
      schema:
        type: string
      description: Destination filter (city, region, or country)
    QueryCheckIn:
      name: check_in
      in: query
      schema:
        type: string
        format: date
      description: Check-in date (YYYY-MM-DD)
    QueryCheckOut:
      name: check_out
      in: query
      schema:
        type: string
        format: date
      description: Check-out date (YYYY-MM-DD)
    QueryGuests:
      name: guests
      in: query
      schema:
        type: integer
        minimum: 1
        default: 2
      description: Number of guests
    QueryMinPrice:
      name: min_price
      in: query
      schema:
        type: number
        minimum: 0
      description: Minimum price per night
    QueryMaxPrice:
      name: max_price
      in: query
      schema:
        type: number
        minimum: 0
      description: Maximum price per night
    QueryPropertyType:
      name: property_type
      in: query
      schema:
        type: string
      description: Property type filter
    QueryMinRating:
      name: min_rating
      in: query
      schema:
        type: number
        minimum: 0
        maximum: 5
      description: Minimum guest rating
    QueryPropertyIds:
      name: property_ids
      in: query
      schema:
        type: string
      description: Comma-separated property IDs
    QueryStartDate:
      name: start
      in: query
      schema:
        type: string
        format: date
      description: Start date for analytics range
    QueryEndDate:
      name: end
      in: query
      schema:
        type: string
        format: date
      description: End date for analytics range
    PathPropertyId:
      name: property_id
      in: path
      required: true
      schema:
        type: string
      description: Public property ID

  responses:
    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DistributionError'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DistributionError'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DistributionError'

  schemas:
    DistributionError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string

    FreshnessMeta:
      type: object
      properties:
        data_updated_at:
          type: string
          format: date-time
        served_at:
          type: string
          format: date-time
        cache_status:
          type: string
          enum: [HIT, MISS, STALE]
        freshness:
          type: string
          enum: [current, stale, unknown]

    PaginationMeta:
      type: object
      properties:
        limit:
          type: integer
        next_cursor:
          type: string
        has_more:
          type: boolean
        total_count:
          type: integer

    SearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PropertyDistributionRecord'
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
        meta:
          $ref: '#/components/schemas/FreshnessMeta'

    PropertyResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/PropertyDistributionRecord'
        meta:
          $ref: '#/components/schemas/FreshnessMeta'

    PropertyDistributionRecord:
      type: object
      properties:
        public_property_id:
          type: string
        property_name:
          type: string
        description:
          type: string
        category:
          type: string
        destination:
          type: string
        address:
          type: string
        coordinates:
          type: object
          properties:
            lat:
              type: number
            lng:
              type: number
        photographs:
          type: array
          items:
            type: string
        amenities:
          type: array
          items:
            type: string
        room_descriptions:
          type: array
          items:
            type: string
        public_pricing:
          type: object
          properties:
            currency:
              type: string
            min:
              type: number
            max:
              type: number
        booking_policies:
          type: array
          items:
            type: string
        booking_mode:
          type: string
        publication_status:
          type: string
          enum: [published, suspended, removed, restricted]
        distribution_eligible:
          type: boolean
        public_rating:
          type: number
        data_updated_at:
          type: string
          format: date-time

    AvailabilityResult:
      type: object
      properties:
        property_id:
          type: string
        available:
          type: boolean
        available_dates:
          type: array
          items:
            type: string
            format: date

    PricingResult:
      type: object
      properties:
        property_id:
          type: string
        currency:
          type: string
        min_price:
          type: number
        max_price:
          type: number
        price_per_night:
          type: number

    Integration:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        integration_type:
          type: string
        registered_domains:
          type: array
          items:
            type: string
        verified_domains:
          type: array
          items:
            type: string
        permitted_widgets:
          type: array
          items:
            type: string
        status:
          type: string
        widget_token:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateIntegrationRequest:
      type: object
      required:
        - name
        - integration_type
      properties:
        name:
          type: string
        integration_type:
          type: string
          enum: [server_side, embedded_search, embedded_feed, property_widget, destination_collection]
        registered_domains:
          type: array
          items:
            type: string
        permitted_widgets:
          type: array
          items:
            type: string

    UpdateIntegrationRequest:
      type: object
      properties:
        name:
          type: string
        registered_domains:
          type: array
          items:
            type: string
        verified_domains:
          type: array
          items:
            type: string
        permitted_widgets:
          type: array
          items:
            type: string
        status:
          type: string
          enum: [active, suspended, removed]

    ApiCredential:
      type: object
      properties:
        id:
          type: string
        account_id:
          type: string
        account_type:
          type: string
        credential_id:
          type: string
        prefix:
          type: string
        status:
          type: string
        permissions:
          type: array
          items:
            type: string
        administrator_granted_permissions:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
        revoked_at:
          type: string
        replaced_by:
          type: string
        replaces:
          type: string
        rotation_count:
          type: integer

    CreateCredentialRequest:
      type: object
      properties:
        name:
          type: string
        permissions:
          type: array
          items:
            type: string

    ReplaceCredentialRequest:
      type: object
      properties:
        permissions:
          type: array
          items:
            type: string

    UpdatePermissionsRequest:
      type: object
      required:
        - permissions
      properties:
        permissions:
          type: array
          items:
            type: string

    AnalyticsOverview:
      type: object
      properties:
        total_requests:
          type: integer
        successful_requests:
          type: integer
        failed_requests:
          type: integer
        success_rate:
          type: string

    ActivityLogEntry:
      type: object
      properties:
        request_id:
          type: string
        endpoint:
          type: string
        method:
          type: string
        response_status:
          type: integer
        processing_time_ms:
          type: integer
        timestamp:
          type: string
          format: date-time
        permission_evaluated:
          type: string
        result_category:
          type: string
