openapi: 3.0.3

info:
  title: Aptly Portal API
  description: >
    HTTP API for the Aptly rental application screening portal.
    Used by prospective tenants, showing agents, and property management staff.
  version: "1.0.0"

servers:
  - url: https://app.getaptly.com/api/portal
    description: Production
  - url: https://www.workturbo.net/api/portal
    description: Staging
  - url: http://localhost:3000/api/portal
    description: Development

security: []

components:
  schemas:
    # ─── Shared primitives ────────────────────────────────────────────────────

    Address:
      type: object
      properties:
        formattedAddress:
          type: string
          example: "123 Main St, Austin TX 78701"
        state:
          type: string
          example: "TX"
        countryName:
          type: string
          example: "United States"

    Error:
      type: object
      properties:
        reason:
          type: string
          example: "human-readable error string"

    # ─── Company / Context ────────────────────────────────────────────────────

    CompanyInfo:
      type: object
      properties:
        requireBankConnect:
          type: boolean
        disableApplicantGuarantors:
          type: boolean
        disableBankScreening:
          type: boolean
        requireEmergencyContact:
          type: boolean
        applicationLock:
          type: string
          example: "onClose"
        enableSection8:
          type: boolean
        enableRegionalScreeningFilters:
          type: boolean
        collectPayment:
          type: boolean
        taxDocumentCount:
          type: integer
        bankStatementCount:
          type: integer
        payStubCount:
          type: integer
        toggleChatWindow:
          type: boolean

    ApplicationConfig:
      type: object
      properties:
        availableDate:
          type: string
          example: "2026-04-01"
        marketRent:
          type: string
          example: "$1,500"
        marketRentValue:
          type: integer
          description: Monthly rent in cents
          example: 150000
        incomeToRent:
          type: number
          example: 3
        marketingTitle:
          type: string
        marketingBlurb:
          type: string
        applicationRequirements:
          type: string
          description: HTML string
        petRestrictions:
          type: string
          description: HTML string
        leaseTerms:
          type: string
          description: HTML string
        coverPhoto:
          type: array
          items:
            type: string
            format: uri
        marketingImages:
          type: array
          items:
            type: string
            format: uri
        agent:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            phone:
              type: string
            photo:
              type: string
              format: uri

    LocationObject:
      type: object
      properties:
        _id:
          type: string
          example: "loc_xyz789"
        name:
          type: string
          example: "The Residences at Oak Creek - Unit 204"
        companyId:
          type: string
          example: "org_abc123"
        address:
          $ref: "#/components/schemas/Address"
        bedCount:
          type: integer
          example: 2
        bathCount:
          type: integer
          example: 1
        squareFeet:
          type: integer
          example: 950
        marketRent:
          type: string
          example: "$1,500"
        marketRentValue:
          type: integer
          example: 150000
        videoUrl:
          type: string
          format: uri
        virtualTourUrl:
          type: string
          format: uri
        applicationConfig:
          $ref: "#/components/schemas/ApplicationConfig"
        companyInfo:
          $ref: "#/components/schemas/CompanyInfo"

# ─── Paths ────────────────────────────────────────────────────────────────────

paths:
  # ── Context & Locations ──────────────────────────────────────────────────────

  /context/{contextId}:
    get:
      operationId: get-context-contextid
      summary: Load property/location context
      tags: [Context & Locations]
      security: []
      parameters:
        - name: contextId
          in: path
          required: true
          schema:
            type: string
        - name: audience
          in: query
          schema:
            type: string
            enum: [applicant, approver, showing]
        - name: bp
          in: query
          description: Show property regardless of publish status
          schema:
            type: boolean
      responses:
        "200":
          description: Location/context object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocationObject"

  /company/{contextId}:
    get:
      operationId: get-company-contextid
      summary: Load company-level config
      tags: [Context & Locations]
      security: []
      parameters:
        - name: contextId
          in: path
          required: true
          schema:
            type: string
        - name: locationContextId
          in: query
          schema:
            type: string
        - name: bp
          in: query
          schema:
            type: boolean
      responses:
        "200":
          description: Company config
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocationObject"

  /locations/{orgId}:
    get:
      operationId: get-locations-orgid
      summary: List all locations for an organization
      tags: [Context & Locations]
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
        - name: available
          in: query
          schema:
            type: string
        - name: bedCount
          in: query
          schema:
            type: integer
        - name: search
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Array of locations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LocationObject"

  /listings/{orgId}/{segmentId}:
    get:
      operationId: get-listings-orgid-segmentid
      summary: List public property listings
      tags: [Context & Locations]
      security: []
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
        - name: segmentId
          in: path
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Array of listings
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/LocationObject"

  /listing/{locationId}:
    get:
      operationId: get-listing-locationid
      summary: Get single listing details
      tags: [Context & Locations]
      security: []
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Location/listing object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocationObject"

  /schools/{locationId}:
    get:
      operationId: get-schools-locationid
      summary: Get nearby schools for a property
      tags: [Context & Locations]
      security: []
      parameters:
        - name: locationId
          in: path
          required: true
          schema:
            type: string
        - name: distance
          in: query
          schema:
            type: integer
            default: 25
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        "200":
          description: Array of school objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    _id:
                      type: string
                    name:
                      type: string
                    type:
                      type: string
                    rating:
                      type: integer
                    distance:
                      type: number
                    address:
                      type: string
                    url:
                      type: string
                      format: uri

  # ── Knowledge Base ───────────────────────────────────────────────────────────

  /knowledge/{knowledgeId}:
    get:
      operationId: get-knowledge-knowledgeid
      summary: Get knowledge base document
      tags: [Knowledge Base]
      security: []
      parameters:
        - name: knowledgeId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Knowledge document
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                  title:
                    type: string
                  slug:
                    type: string
                  content:
                    type: string
                  contentType:
                    type: string
                    enum: [html, markdown]
                  category:
                    type: string
                  tags:
                    type: array
                    items:
                      type: string
                  publishedAt:
                    type: string
                    format: date-time
                  updatedAt:
                    type: string
                    format: date-time
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # ── Forms ───────────────────────────────────────────────────────────────────

  /forms/{formId}/{cardId}/{boardId}:
    get:
      operationId: get-forms-formid-cardid-boardid
      summary: Get embeddable form definition
      tags: [Forms]
      security: []
      parameters:
        - name: formId
          in: path
          required: true
          schema:
            type: string
        - name: cardId
          in: path
          required: true
          schema:
            type: string
        - name: boardId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Form definition
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                  title:
                    type: string
                  fields:
                    type: array
                    items:
                      type: object
                  submitLabel:
                    type: string
                  companyId:
                    type: string
                  locationId:
                    type: string

  /forms/submit:
    post:
      operationId: post-forms-submit
      summary: Submit a completed form
      tags: [Forms]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [formId, cardId, boardId, data]
              properties:
                formId:
                  type: string
                cardId:
                  type: string
                boardId:
                  type: string
                data:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: boolean
                  message:
                    type: string

  /forms/searchLocations:
    post:
      operationId: post-forms-searchlocations
      summary: Search locations for form location picker
      tags: [Forms]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [companyId]
              properties:
                query:
                  type: string
                companyId:
                  type: string
                bedCount:
                  type: integer
                maxRent:
                  type: integer
                  description: Maximum rent in cents
      responses:
        "200":
          description: Location results
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: array
                    items:
                      $ref: "#/components/schemas/LocationObject"
