FairePlace Health API

openapi: 3.2.0
info:
  title: FairePlace Property Management Health API
  description: 'Comprehensive API for managing properties, leases, tenants, and all aspects of real estate management.

    Built with Rust and Actix-web following hexagonal architecture principles.


    ## Authentication

    This API uses API keys for authentication with tenant-based isolation.


    ## Base URL

    - Production: `https://api.faireplace.com/api`'
  version: 1.0.0
  contact:
    name: FairePlace API Support
    email: api-support@faireplace.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.faireplace.com/api
  description: Production server
security:
- BearerAuth: []
tags:
- name: Health
  description: API health check endpoints
paths:
  /health:
    get:
      operationId: livenessCheck
      summary: Liveness check
      description: 'Answers `200` as long as the process is up. **Does not touch the

        database**: this is the endpoint uptime monitors should poll.


        Use `/ready` instead when you need to know the API can actually serve

        traffic (deployment gates, smoke tests).'
      tags:
      - Health
      security: []
      responses:
        '200':
          description: The API process is alive
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /ready:
    get:
      operationId: readinessCheck
      summary: Readiness check
      description: 'Verifies the API can reach its database (`SELECT 1`) and answers `200`

        only then.


        **Do not poll this.** Every call wakes the serverless database and keeps

        it from suspending, which costs real money. Use it for deployment checks

        and smoke tests; point your uptime monitor at `/health` instead.'
      tags:
      - Health
      security: []
      responses:
        '200':
          description: The API is ready to serve traffic
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ready
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: The database is unreachable
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: unavailable
                  error:
                    type: string
                    example: Database connection failed
components:
  schemas:
    Error:
      type: object
      description: "The error envelope returned by every authenticated endpoint.\n\nTwo things are worth knowing before you write your error handling:\n\n- **`code` is a symbolic string, not a number.** The numeric HTTP status is\n  in `status`. Branch on `code`: it is stable, and show `message`, which\n  is written for humans and may be reworded without notice.\n- The public guest-signature endpoints use a **different, flatter shape**\n  (`{ \"error_code\": …, \"message\": … }`, no `error` wrapper), because they\n  are consumed by a page that has no session. Their responses document it\n  inline.\n\nThe `X-Request-Id` response header carries the request identifier: quote it\nwhen reporting a problem. It is a header, not a body field.\n"
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - status
          properties:
            code:
              type: string
              description: Stable symbolic code. Branch on this.
              enum:
              - NOT_FOUND
              - UNAUTHORIZED
              - VALIDATION_ERROR
              - DATABASE_ERROR
              - BUSINESS_ERROR
              - STORAGE_ERROR
              - CONFIG_ERROR
              - FORBIDDEN
              - CONFLICT
              - PARSE_ERROR
              - SERIALIZATION_ERROR
              - AUTHENTICATION_ERROR
              - AUTHORIZATION_ERROR
              - EXTERNAL_SERVICE_ERROR
              - RATE_LIMIT_EXCEEDED
              - PAYMENT_REQUIRED
              - PLAN_LIMIT_REACHED
              - GONE
              - BAD_REQUEST
              - INTERNAL_ERROR
              - INTERNAL_SERVER_ERROR
              example: NOT_FOUND
            message:
              type: string
              description: 'Human-readable explanation, most often in French. Safe to display,

                not safe to parse.

                '
              example: Lease not found
            status:
              type: integer
              description: The HTTP status code, repeated in the body.
              example: 404
            details:
              type: object
              additionalProperties: true
              description: 'Extra machine-readable context. Only present on some errors: on

                `RATE_LIMIT_EXCEEDED` it carries `retry_after_seconds`.

                '
              example:
                retry_after_seconds: 12
  responses:
    TooManyRequests:
      description: 'Rate limit exceeded. Every endpoint sits behind a plan-aware limiter, and

        the public tools carry an additional per-endpoint one.


        `error.details.retry_after_seconds` says how long to wait; the

        `Retry-After`, `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers

        carry the same information.

        '
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute for this plan and category.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests left in the current window.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RATE_LIMIT_EXCEEDED
              message: Trop de requêtes. Réessayez plus tard.
              status: 429
              details:
                retry_after_seconds: 12
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key with fp_* prefix, passed as Bearer token
    WorkerApiKey:
      type: apiKey
      in: header
      name: X-API-Key
    WorkerBearer:
      type: http
      scheme: bearer
      bearerFormat: Worker